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Preface 


About  This  Manual 

This  manual  describes  the  X  library,  the  C  Language  programming  interface  to  Version  1 1  of 
the  X  Window  System.  The  X  library,  known  as  Xlib,  is  the  lowest  level  of  programming 
interface  to  X.  This  library  enables  a  programmer  to  write  applications  with  an  advanced 
user  interface  based  on  windows  on  the  screen,  with  complete  network  transparency,  that  will 
run  without  changes  on  many  types  of  workstations  and  personal  computers. 

Xlib  is  powerful  enough  to  write  effective  applications  without  additional  programming  tools 
and  is  necessary  for  certain  tasks  even  in  applications  written  with  higher-level  "toolkits." 

There  are  a  number  of  these  toolkits  for  X  programming,  the  most  notable  being  the 
DEC/MIT  toolkit  Xt,  the  Andrew  toolkit  developed  by  IBM  and  Carnegie-Mellon  University, 
and  the  Interviews  toolkit  from  Stanford.  These  toolkits  are  still  evolving,  and  only  Xt  is 
currently  part  of  the  X  standard.  Toolkits  simplify  the  process  of  application  writing  con 
siderably,  providing  a  number  of  widgets  that  implement  menus,  command  buttons,  and  other 
common  features  of  the  user  interface. 

This  manual  does  not  describe  Xt  or  any  other  toolkit.  That  is  done  in  Volumes  Four,  Five, 
and  Six  of  our  X  Window  System  series.  Nonetheless,  much  of  the  material  described  in  this 
book  is  helpful  for  understanding  and  using  the  toolkits,  since  the  toolkits  themselves  are 
written  using  Xlib  and  allow  Xlib  code  to  be  intermingled  with  toolkit  code. 


Summary  of  Contents 

This  manual  is  divided  into  two  volumes.  This  is  the  second  volume,  the  Xlib  Reference 
Manual.  It  includes  reference  pages  for  each  of  the  Xlib  functions  (organized  alphabeti 
cally),  a  permuted  index,  and  numerous  appendices  and  quick  reference  aids. 

The  first  volume,  the  Xlib  Programming  Manual,  provides  a  conceptual  introduction  to  Xlib, 
including  tutorial  material  and  numerous  programming  examples.  Arranged  by  task  or  topic, 
each  chapter  brings  together  a  group  of  Xlib  functions,  describes  the  conceptual  foundation 
they  are  based  on,  and  illustrates  how  they  are  most  often  used  in  writing  applications  (or,  in 
the  case  of  the  last  chapter,  in  writing  window  managers).  Volume  One  is  structured  so  as  to 
be  useful  as  a  tutorial  and  also  as  a  task-oriented  reference. 
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Volume  One  and  Volume  Two  are  designed  to  be  used  together.  To  get  the  most  out  of  the 
examples  in  Volume  One,  you  will  need  the  exact  calling  sequences  of  each  function  from 
Volume  Two.  To  understand  fully  how  to  use  each  of  the  functions  described  in  Vol 
ume  Two,  all  but  the  most  experienced  X  "hacker"  will  need  the  explanation  and  examples  in 
Volume  One. 

Both  volumes  include  material  from  the  original  Xlib  and  XI 1  Protocol  documentation  pro 
vided  by  MIT,  as  well  as  from  other  documents  provided  on  the  MIT  release  tape.  We  have 
done  our  best  to  incorporate  all  of  the  useful  information  from  the  MIT  documentation,  to 
correct  references  we  found  to  be  in  error,  to  reorganize  and  present  it  in  a  more  useful  form, 
and  to  supplement  it  with  conceptual  material,  tutorials,  reference  aids,  and  examples.  In 
other  words,  this  manual  is  not  only  a  replacement  but  is  a  superset  of  the  MIT  documenta 
tion. 

Those  of  you  familiar  with  the  MIT  documentation  will  recognize  that  each  reference  page  in 
Volume  Two  includes  the  detailed  description  of  the  routine  found  in  Gettys,  Newman,  and 
Scheifler's  Xlib-C  Language  X  Interface,  plus,  in  many  cases,  additional  text  that  clarifies 
ambiguities  and  describes  the  context  in  which  the  routine  would  be  used.  We  have  also 
added  cross  references  to  related  reference  pages  and  to  where  additional  information  can  be 
found  in  Volume  One. 


How  to  Use  This  Manual 

Volume  Two  is  designed  to  make  it  as  easy  and  fast  as  possible  to  look  up  virtually  any  fact 
about  Xlib.  It  includes  a  permuted  index,  reference  pages  for  each  library  function,  appen 
dices  that  cover  macros,  structures,  function  groups,  events,  fonts,  colors,  cursors,  keysyms, 
and  errors,  and  at-a-glance  tables  for  the  graphics  context  and  window  attributes. 

The  permuted  index  is  the  standard  UNIX  way  of  finding  a  particular  function  name  given  a 
keyword.  By  looking  up  a  word  in  the  second  column  that  you  think  describes  the  function 
you  are  looking  for,  you  can  find  the  group  of  functions  that  have  that  word  in  their  descrip 
tion  lines.  The  description  line  also  appears  at  the  top  of  each  reference  page.  Once  you 
have  found  the  routine  you  are  looking  for,  you  can  look  for  its  reference  page. 

The  reference  pages  themselves  provide  all  the  details  necessary  for  calling  each  routine, 
including  its  arguments,  returned  values,  definitions  of  the  structure  types  of  arguments  and 
returned  values,  and  the  errors  it  may  generate.  Many  of  the  pages  also  give  hints  about  how 
the  routine  is  used  in  the  context  of  other  routines.  This  is  the  part  of  this  volume  you  will 
use  the  most. 

Appendix  A,  Function  Group  Summary,  groups  the  routines  according  to  function,  and  pro 
vides  brief  descriptions.  You'll  find  it  useful  to  have  in  one  place  a  description  of  related 
routines,  so  their  differences  can  be  noted  and  the  appropriate  one  chosen. 

Appendix  B,  Error  Messages  and  Protocol  Requests,  describes  the  errors  that  Xlib  routines 
can  generate.  When  an  error  is  handled  by  the  default  error  handler,  one  of  these  messages  is 
printed.  Also  printed  is  the  X  Protocol  request  that  caused  the  error.  Since  Protocol  requests 
do  not  map  directly  to  Xlib  routines,  this  appendix  provides  a  table  with  which  you  can  find 
out  which  Xlib  routine  in  your  code  caused  the  error. 
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Appendix  C,  Macros,  describes  the  macros  that  access  members  of  the  Display  structure, 
classify  keysyms,  and  convert  resource  manager  types. 

Appendix  D,  ColorCaEE,  presents  the  standard  color  database.  The  color  names  in  this  data 
base  should  be  available  on  all  servers,  though  the  corresponding  RGB  values  may  have  been 
modified  to  account  for  screen  variations. 

Appendix  E,  Event  Reference,  describes  each  event  type  and  structure,  in  a  reference  page 
format.  This  is  an  invaluable  reference  for  event  programming. 

Appendix  F,  Structure  Reference,  describes  all  structures  used  by  Xlib  except  the  event  struc 
tures  described  in  Appendix  E,  including  which  routines  use  each  structure. 

Appendix  G,  Symbol  Reference,  lists  in  alphabetical  order  and  describes  all  of  the  symbols 
defined  in  Xlib  include  files. 

Appendix  H,  Keysym  Reference,  lists  and  describes  each  character  in  the  standard  keysym 
families,  used  for  translating  keyboard  events.  The  characters  for  English  and  foreign  lan 
guage  keysyms  are  shown  where  possible. 

Appendix  I,  The  Cursor  Font,  describes  the  standard  cursor  font,  including  a  illustration  of 
the  font  shapes. 

Appendix  J,  The  Xmu  Library,  provides  reference  pages  for  each  function  in  the  miscella 
neous  utilities  library.  This  library  is  provided  with  the  standard  X  distribution  and  is  very 
useful  when  programming  with  Xlib. 

Finally,  Volume  Two  concludes  with  at-a-glance  charts  that  help  in  setting  the  graphics  con 
text  (GC)  and  the  window  attributes. 


Example  Programs 

The  example  programs  in  this  book  are  on  the  XI 1  Release  4  distribution  in  the  contributed 
section.  There  are  many  ways  of  getting  this  distribution;  most  are  described  in  Appendix  H. 

The  example  programs  are  also  available  free  from  UUNET  (that  is,  free  except  for  UUNET's 
usual  connect-time  charges).  If  you  have  access  to  UUNET,  you  can  retrieve  the  source  code 
using  uucp  orftp.  For  uucp,  find  a  machine  with  direct  access  to  UUNET  and  type  the  follow 
ing  command: 

uucp   uunet\ ! ~uucp/nutshell/Xlib/xlibprgs.tar .Z    yourhosW '/yourname/ 

The  backslashes  can  be  omitted  if  you  use  the  Bourne  shell  (sh)  instead  of  csh.  The  file 
should  appear  some  time  later  (up  to  a  day  or  more)  in  the  directory  lusrlspoolluucp- 
publicl yourname. 

To  ustftp,ftp  to  uunet.uu.net  and  use  anonymous  as  your  user  name  and  guest  as  your  pass 
word.  Then  type  the  following: 

cd  /nutshell/Xlib 

binary    ( you  must  specify  binary  transfer  for  compressed  files ) 

get  xlibprgs.tar.Z 

bye 
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The  file  is  a  compressed  tar  archive.  To  restore  the  files  once  you  have  retrieved  the  archive, 
type: 

uncompress  xlibprgs.tar 
tar  xvf  xlibprgs.tar 

The  example  programs  are  also  available  free  by/fp  from  expo.lcs.mit.edu.  The  directory 
containing  the  examples  is  contriblexampleslOReillylXlib . 

The  examples  will  be  installed  in  subdirectories  under  the  current  directory,  one  for  each 
chapter  in  the  book.  Imakefiles  are  included.  (Imakefiles  are  used  with  imake,  a  program 
supplied  with  the  XI 1  distribution  that  generates  proper  Makefiles  on  a  wide  variety  of  sys 
tems.) 

Assumptions 

Readers  should  be  proficient  in  the  C  programming  language,  although  examples  are  pro 
vided  for  infrequently  used  features  of  the  language  that  are  necessary  or  useful  when  pro 
gramming  with  X.  In  addition,  general  familiarity  with  the  principles  of  raster  graphics  will 
be  helpful. 

Font  Conventions  Used  in  This  Manual 


Italic  is  used  for: 

•  UNIX  pathnames,  filenames,  program  names,  user  command  names,  and  options  for  user 
commands. 

•  New  terms  where  they  are  defined. 

Typewriter   Font  is  used  for: 

•  Anything  that  would  be  typed  verbatim  into  code,  such  as  examples  of  source  code  and 
text  on  the  screen. 

•  The  contents  of  include  files,  such  as  structure  types,  structure  members,  symbols 
(defined  constants  and  bit  flags),  and  macros. 

•  Xlib  functions. 

•  Names  of  subroutines  of  the  example  programs. 

Italic    Typewri  ter  Fon  t  is  used  for: 

•  Arguments  to  Xlib  functions,  since  they  could  be  typed  in  code  as  shown  but  are  arbi 
trary. 

Helvetica  Italics  are  used  for: 

•  Titles  of  examples,  figures,  and  tables. 
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Boldface  is  used  for: 

•     Chapter  and  section  headings. 

Related  Documents 

The  C  Programming  Language  by  B.  W.  Kernighan  and  D.  M.  Ritchie 
The  following  documents  are  included  on  the  XI 1  source  tape: 

Xt  Toolkit  Intrinsics  by  Joel  McCormack,  Paul  Asente,  and  Ralph  Swick 

Xt  Toolkit  Widgets  by  Ralph  Swick  and  Terry  Weissman 

Xlib-C  Language  X  Interface  by  Jim  Gettys,  Ron  Newman,  and  Robert  Scheifler 

X  Window  System  Protocol,  Version  11  by  Robert  Scheifler 

The  following  books  on  the  X  Window  System  are  available  from  O'Reilly  and  Associates, 
Inc.: 

Volume  Zero  —  X  Protocol  Reference  Manual 

Volume  Three  —  X  Window  System  User's  Guide 

Volume  Four  —  X  Toolkit  Intrinsics  Programming  Manual 

Volume  Five  —  X  Toolkit  Intrinsics  Reference  Manual 

Volume  Six  — X  Toolkit  Widgets  Reference  Manual  (available  summer  1990) 

Volume  Seven  — XView  Programmer's  Guide 

Quick  Reference  —  The  X  Window  System  in  a  Nutshell 

Requests  for  Comments 

Please  write  to  tell  us  about  any  flaws  you  find  in  this  manual  or  how  you  think  it  could  be 
improved,  to  help  us  provide  you  with  the  best  documentation  possible. 

Our  U.S.  mail  address,  e-mail  address,  and  telephone  number  are  as  follows: 

O'Reilly  and  Associates,  Inc. 
632  Petaluma  Avenue 
Sebastopol,  CA  95472 
(800)  338-6887 

UUCP:  uunet!ora!adrian  ARPA:  adrian@ora.UU.NET 
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Bulk  Sales  Information 

This  manual  is  being  resold  as  the  official  X  Window  System  documentation  by  many  work 
station  manufacturers.  For  information  on  volume  discounts  for  bulk  purchase,  call  Linda 
Walsh  at  O'Reilly  and  Associates,  Inc.,  at  617-354-5800,  or  send  e-mail  to  linda@ora.com. 

For  companies  requiring  extensive  customization  of  the  book,  source  licensing  terms  are  also 
available. 
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How  to  Use  the  Permuted  Index 

The  permuted  index  takes  the  brief  descriptive  string  from  the  title  of  each  command  page 
and  rotates  (permutes)  the  string  so  that  each  keyword  will  at  one  point  start  the  second,  or 
center,  column  of  the  line.  The  beginning  and  end  of  the  original  string  are  indicated  by  a 
slash  when  they  are  in  other  than  their  original  position;  if  the  string  is  too  long,  it  is  trun 
cated. 

To  find  the  command  you  want,  simply  scan  down  the  middle  of  the  page,  looking  for  a  key 
word  of  interest  on  the  right  side  of  the  blank  gutter.  Once  you  find  the  keyword  you  want, 
you  can  read  (with  contortions)  the  brief  description  of  the  command  that  makes  up  the  entry. 
If  things  still  look  promising,  you  can  look  all  the  way  over  to  the  right  for  the  name  of  the 
relevant  command  page. 
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for  string  and  font  metrics  of  a  16-bit  character  string  /server XQueryTextExtents  1 6 

/get  string  and  font  metrics  of  a  16-bit  character  string,  locally XTextExtentsl6 

/get  the  width  in  pixels  of  a  1 6-bit  character  string,  locally XTextWidth  1 6 

XDrawImageStringl6:  draw  16-bit  image  text  characters  XDrawImageStringl6 

XDrawTextl6:  draw  16-bit  polytext  strings  XDrawTextl6 

/get  the  width  in  pixels  of  an  8-bit  character  string,  locally XTextWidth 

XDrawImageString:  draw  8-bit  image  text  characters XDrawImageString 

XDrawText:  draw  8-bit  polytext  strings  XDrawText 

only  XDrawString:  draw  an  8-bit  text  string,  foreground XDrawString 

/disable  or  enable  access  control  XSetAccessControl 

XAddHost:  add  a  host  to  the  access  control  list  XAddHost 

add  multiple  hosts  to  the  access  control  list  XAddHosts: XAddHosts 

/remove  a  host  from  the  access  control  list XRemoveHost 

/remove  multiple  hosts  from  the  access  control  list XRemoveHosts 

deny/  XEnableAccessControl:  use  access  control  list  to  allow  or XEnableAccessControl 

XDisableAccessControl:  allow  access  from  any  host XDisableAccessControl 

/obtain  a  b'st  of  hosts  having  access  to  this  display XListHosts 

XActivateScreenSaver:  activate  screen  blanking  XActivateScreenSaver 

release  the  keyboard  from  an  active  grab  XUngrabKeyboard:  XUngrabKeyboard 

release  the  pointer  from  an  active  grab  XUngrabPointer: XUngrabPointer 

/change  the  parameters  of  an  active  pointer  grab XChangeActivePointerGrab 

pixel  value  in  an/  XAddPixel:  add  a  constant  value  to  every XAddPixel 

b'st  XAddHost:  add  a  host  to  the  access  control XAddHost 
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XInsertModifiermapEntry:  add  a  new  entry  to  an/ XInsertModifiermapEntry 

XUnionRectWithRegion:  add  a  rectangle  to  a  region XUnionRectWithRegion 

a/  XrmQPutStringResource:  add  a  resource  specification  to XrmQPutStringResource 

a  resource/  XrmPutLineResource:  add  a  resource  specification  to XrmPutLineResource 

with/  XrmPutStringResource:  add  a  resource  specification  XrmPutStringResource 

save-set  XAddToSaveSet:  add  a  window  to  the  client's XAddToSaveSet 

control  list  XAddHosts:  add  multiple  hosts  to  the  access XAddHosts 

the  client's/  XChangeSaveSet:  add  or  remove  a  sub  window  from  XChangeSaveSet 

XrmUniqueQuark:  allocate  a  new  quark  XrmUniqueQuark 

from  color/  XAUocNamedColor:  aUocate  a  read-only  colorcell  XAUocNamedColor 

cell  with  closest/  XAUocColor:  aUocate  a  read-only  colormap XAllocColor 

XAllocClassHint:  allocate  an  XClassHint  structure XAUocClassHint 

XAllocIconSize:  allocate  an  XlconSize  structure XAllocIconSize 

XAllocSizeHints:  allocate  an  XSizeHints  structure XAllocSizeHints 

XAllocStandardColormap:  allocate  an  XStandardColormap/ XAllocStandardColormap 

XAllocWMHints:  aUocate  an  XWMHints  structure XAllocWMHints 

structure  XCreatelmage:  allocate  memory  for  an  Xlmage XCreatelmage 

freed  Xpermalloc:  allocate  memory  never  to  be  Xpermalloc 

XAllocColorPlanes:  aUocate  read/write/ XAUocColorPlanes 

colorceUs  XAUocColorCeUs:  aUocate  read/write  (nonshared) XAUocColorCeUs 

XFree:  free  specified  memory  aUocated  by  an  Xlib  function  XFree 

XFreeFontPath:  free  the  memory  aUocated  by  XGetFontPath  XFreeFontPath 

XFreeFontNames:  free  the  memory  aUocated  by  XListFonts XFreeFontNames 

XFreeFontlnfo:  free  the  memory  aUocated  by  XListFonts Withlnfo XFreeFontlnfo 

XFreeExtensionList:  free  memory  aUocated  for  a  list  of/ XFreeExtensionList 

table,  /free  the  memory  aUocated  for  an  association  XDestroyAssocTable 

XDisableAccessControl:  aUow  access  from  any  host XDisableAccessControl 

/use  access  control  Ust  to  aUow  or  deny  connection/ XEnableAccessControl 

colormap;  instaU  default  if  not  already  instaUed  /uninstaU  a  XUninstaUColormap 

XLoadFont:  load  a  font  if  not  already  loaded;  get  font  ID XLoadFont 

contents  of  one  database  into  another  /merge  the XrmMergeDatabases 

subtract  one  region  from  another  XSubtractRegion:  XSubtractRegion 

system  from  one  window  to  another  /change  the  coordinate XTranslateCoordinates 

/move  the  pointer  to  another  point  on  the  screen XWarpPointer 

/insert  a  window  between  another  window  and  its  parent  XReparentWindow 

into  a  drawable  with  depth,  applying  pixel  values  /drawable XCopyPlane 

/convert  a  keysym  to  the  appropriate  keycode XKeysymToKeycode 

XFiUArc:  fdl  an  arc XFiUArc 

XDrawArc:  draw  an  arc  fitting  inside  a  rectangle  XDrawArc 

XSetArcMode:  set  the  arc  mode  in  a  graphics  context XSetArcMode 

XDrawArcs:  draw  multiple  arcs  XDrawArcs 

XFiUArcs:  fiU  multiple  arcs  XFiUArcs 

fiU  a  rectangular  area  XFiURectangle: XFillRectangle 

XClearArea:  clear  a  rectangular  area  in  a  window  XClearArea 

XCopyArea:  copy  an  area  of  a  drawable  XCopyArea 

fiU  multiple  rectangular  areas  XFillRectangles:  XFillRectangles 

database  from  command  line  arguments  /load  a  resource  XrmParseCommand 

XA_WM_COMMAND  atom  (command  line  arguments)  XSetCommand:  set  the XSetCommand 

properties  in  the  properties  array  /rotate XRotateWindowProperties 

/obtain  RGB  values  for  an  array  of  colorceUs XQueryColors 

/look  up  RGB  values  from  ASCII  color  name  or  translate/ XParseColor 

/map  a  key  event  to  ASCII  string,  keysym,  and/ XLookupString 

XDefineCursor:  assign  a  cursor  to  a  window  XDefineCursor 

the  window  manager  XStoreName:  assign  a  name  to  a  window  for XStoreName 

/deaUocate  storage  associated  with  a  region XDestroyRegion 

/change  a  property  associated  with  a  window XChangeProperty 

XDestroylmage:  deallocate  memory  associated  with  an  image XDestroylmage 

/the  GContext  (resource  ID)  associated  with  the  specified/ XGContextFromGC 
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/the  XStandardColoimap  structure  associated  with  the  specified/ XGetRGBColormaps 

string/  /free  the  in-memory  data  associated  with  the  specified XFreeStringLast 

/delete  an  entry  from  an  association  table XDeleteAssoc 

/free  the  memory  allocated  for  an  association  table XDestroyAssocTable 

obtain  data  from  an  association  table  XLookUpAssoc: XLookUpAssoc 

create  an  entry  in  an  association  table  XMakeAssoc: XMakeAssoc 

XCreateAssocTable:  create  a  new  association  table  (X10) XCreateAssocTable 

name  for  a  property  given  its  atom  XGetAtomName:  get  a  string XGetAtomName 

get  a  font  property  given  its  atom  XGetFontProperty: XGetFontProperty 

/set  the  XA_WM_COMMAND  atom  (command  line  arguments)  XSetCommand 

string  XInternAtom:  return  an  atom  for  a  given  property  name XInternAtom 

XGetWindowProperty:  obtain  the  atom  type  and  property  format/ XGetWindowProperty 

/a  window  border  pixel  value  attribute  and  repaint  the  border XSetWindowBorder 

/change  a  window  border  tile  attribute  and  repaint  the  border XSetWindowBorderPixmap 

/set  the  colormap  attribute  for  a  window XSetWindowColormap 

/set  the  background  pixel  value  attribute  of  a  window XSetWindowBackground 

/change  the  background  tile  attribute  of  a  window XSetWindowBackgroundPixmap 

/set  window  attributes  XChangeWindow Attributes 

create  a  window  and  set  attributes  XCreateWindow:  XCreate Window 

/obtain  the  current  attributes  of  window  XGetWindow Attributes 

/turn  off  the  keyboard  auto-repeat  keys  X  AutoRepeatOff 

turn  on  the  keyboard  auto-repeat  keys  XAutoRepeatOn:  XAutoRepeatOn 

XPutBackEvent:  push  an  event  back  on  the  input  queue XPutBackEvent 

XSetState:  set  the  foreground,  background,  logical  function,/ XSetState 

XSetWindowBackground:  set  the  background  pixel  value  attribute/  XSetWindowBackground 

XSelBackground:  set  the  background  pixel  value  in  a/ XSetBackground 

window  /change  the  background  tile  attribute  of  a  XSetWindowBackgroundPixmap 

XAllowEvents:  control  the  behavior  of  keyboard  and  pointer/ X  AUowEvents 

XBell:  ring  the  bell  (Control  G) XBell 

or/  XQueryBestSize:  obtain  the  "best"  supported  cursor,  tile,  XQueryBestSize 

XReparentWindow:  insert  a  window  between  another  window  and  its/ XReparentWindow 

/calculate  the  difference  between  the  union  and/ XXorRegion 

XDrawLine:  draw  a  line  between  two  points  XDrawLine 

XDraw:  draw  a  polyline  or  curve  between  vertex  list  (from  X10)  XDraw 

/convert  a  key  string  to  a  binding  list  and  a  quark  list  XrmStringToBindingQuarkList 

of  the/  XQueryKeymap:  obtain  a  bit  vector  for  the  current  state XQueryKeymap 

/create  a  pixmap  with  depth  from  bitmap  data XCreatePixmapFromBitmapData 

/create  a  bitmap  from  XI 1  bitmap  format  data  XCreateBitmapFromData 

XReadBitmapFile:  read  a  bitmap  from  disk  XReadBitmapFile 

XCreateBitmapFromData:  create  a  bitmap  from  XI 1  bitmap  format/ XCreateBitmapFromData 

XWriteBitmapFile:  write  a  bitmap  to  a  file XWriteBitmapFile 

create  a  cursor  from  two  bitmaps  XCreatePixmapCursor: XCreatePixmapCursor 

graphics/  XSetFunction:  set  the  bitwise  logical  operation  in  a XSetFunction 

activate  screen  blanking  XActivateScreenSaver:  XActivateScreenSaver 

value  attribute  and  repaint  the  border  /a  window  border  pixel XSetWindowBorder 

tile  attribute  and  repaint  the  border  /change  a  window  border XSetWindowBorderPixmap 

repaint  the/  /change  a  window  border  pixel  value  attribute  and  XSetWindowBorder 

repaint  the/  /change  a  window  border  tile  attribute  and XSetWindowBorderPixmap 

/change  the  border  width  of  a  window XSetWindowBorderWidth 

/the  window  position,  size,  border  width,  or  stacking  order XConfigureWindow 

/remove  the  next  event  matching  both  passed  window  and  passed/ XCheckWindowEvent 

stacking  order  /circulate  the  bottom  child  to  the  top  of  the  XCirculateSubwindowsDown 

/circulate  the  top  child  to  the  bottom  of  the  stacking  order XCirculateSubwindowsUp 

return  data  from  a  cut  buffer  XFetchBuffen XFetchBuffer 

from  pointer  motion  history  buffer  /get  events XGetMotionEvents 

store  data  in  a  cut  buffer  XStoreBuffer: XStoreBuffer 

return  data  from  cut  buffer  0  XFetchBytes: XFetchBytes 

XStoreBytes:  store  data  in  cut  buffer  0 XStoreBytes 
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XPending:  flush  the  request  buffer  and  return  the  number  of/ XPending 

and/  XSync:  flush  the  request  buffer  and  wait  for  all  events XSync 

XFlush:  flush  the  request  buffer  (display  all  queued/ XFlush 

XRotateBuffers:  rotate  the  cut  buffers XRotateBuffers 

XGrabButton:  grab  a  pointer  button  XGrabButton 

XUngrabButton:  release  a  button  from  a  passive  grab  XUngrabButton 

/get  the  pointer  button  mapping  XGetPointerMapping 

/set  the  pointer  button  mapping  XSetPointerMapping 

of  a  given  GC  from  Xlib's  GC  cache  /obtain  components XGetGCValues 

the  union  and/  XXorRegion:  calculate  the  difference  between XXorRegion 

user  geometry  string/  XGeometry:  calculate  window  geometry  given  XGeometry 

/set  a  function  called  after  all  Xlib  functions XSetAfterFunction 

allocate  a  read-only  colormap  cell  with  closest/  XAllocColon XAllocColor 

with  a  window  XChangeProperty:  change  a  property  associated XChangeProperty 

value/  XSetWindowBorder:  change  a  window  border  pixel XSetWindowBorder 

XSetWindowBorderPixmap:  change  a  window  border  tile/ XSetWindowBorderPixmap 

XResize Window:  change  a  window's  size XResize Window 

context  to/  XSetClipRectangles:  change  clip_mask  in  a  graphics  XSetClipRectangles 

XOffsetRegion:  change  offset  of  a  region  XOffsetRegion 

XSetWindowBackgroundPixmap:  change  the  background  tile/ XSetWindowBackgroundPixmap 

window  XSetWindowBorderWidth:  change  the  border  width  of  a XSetWindowBorderWidth 

client  XSetCloseDownMode:  change  the  close  down  mode  of  a XSetCloseDownMode 

XRecolorCursor:  change  the  color  of  a  cursor XRecolorCursor 

graphics  context  XChangeGC:  change  the  components  of  a  given XChangeGC 

from  one/  XTranslateCoordinates:  change  the  coordinate  system  XTranslateCoordinates 

XChangeKeyboardMapping:  change  the  keyboard  mapping  XChangeKeyboardMapping 

such  as/  XChangeKeyboardControl:  change  the  keyboard  preferences XChangeKeyboardControl 

XChangeActivePointerGrab:  change  the  parameters  of  an/ XChangeActivePointerGrab 

XChangePointerControl:  change  the  pointer  preferences XChangePointerControl 

read/write/  XStoreColor:  set  or  change  the  RGB  values  of  a XStoreColor 

read/write/  XStoreColors:  set  or  change  the  RGB  values  of XStoreColors 

a  window  XMoveResize Window:  change  the  size  and  position  of XMoveResize Window 

siblings  XRestack Windows:  change  the  stacking  order  of XRestack Windows 

property  XSetStandardColormap:  change  the  standard  colormap XSetStandardColormap 

size,  border/  XConfigure Window:  change  the  window  position, XConfigureWindow 

and  font  metrics  of  a  16-bit  character  string  /for  string XQueryTextExtentsl6 

/and  font  metrics  of  a  16-bit  character  string,  locally XTextExtentsl6 

the  width  in  pixels  of  an  8-bit  character  string,  locally  /get XTextWidth 

the  width  in  pixels  of  a  16-bit  character  string,  locally  /get XTextWidthl6 

draw  8-bit  image  text  characters  XDrawImageString:  XDrawImageString 

draw  16-bit  image  text  characters  XDrawImageString  16: XDrawImageString  16 

matching  event  XChecklfEvent:  check  the  event  queue  for  a XChecklfEvent 

the  event  queue  XEventsQueued:  check  the  number  of  events  in XEventsQueued 

stacking/  /circulate  the  top  child  to  the  bottom  of  the XCirculateSubwindowsUp 

order  /circulate  the  bottom  child  to  the  top  of  the  stacking  XCirculateSubwindowsDown 

XQueryTree:  return  a  list  of  children,  parent,  and  root XQueryTree 

/circulate  the  stacking  order  of  children  up  or  down XCirculateSubwindows 

the/  XCirculateSubwindowsDown:  circulate  the  bottom  child  to XCirculateSubwindowsDown 

children/  XCirculateSubwindows:  circulate  the  stacking  order  of XCirculateSubwindows 

bottom/  XCirculateSubwindowsUp:  circulate  the  top  child  to  the  XCirculateSubwindowsUp 

matches  the  desired  depth  and  class  /visual  information  that XMatchVisuallnfo 

a  resource  value  using  name  and  class  as  quarks  /get XrmQGetResource 

/get  a  resource  from  name  and  class  as  strings  XrmGetResource 

window  XClearArea:  clear  a  rectangular  area  in  a XClearArea 

XClearWindow:  clear  an  entire  window XClearWindow 

keyboard  preferences  such  as  key  click  /change  the XChangeKeyboardControl 

rebind  a  keysym  to  a  string  for  client  XRebindKeysym: XRebindKeysym 

change  the  close  down  mode  of  a  client  XSetCloseDownMode: XSetCloseDownMode 
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XKillClient:  destroy  a  client  or  its  remaining/ XKillClient 

and/  XCloseDisplay:  disconnect  a  client  program  from  an  X  server XCloseDisplay 

XOpenDisplay:  connect  a  client  program  to  an  X  server XOpenDisplay 

/add  a  window  to  the  client's  save-set XAddToSaveSet 

or  remove  a  subwindow  from  the  client's  save-set  /add  XChangeSaveSet 

/remove  a  window  from  the  client's  save-set XRemoveFromSaveSet 

context  XSetClipOrigin:  set  the  clip  origin  in  a  graphics  XSetClipOrigin 

to  a/  XSetClipRectangles:  change  clip_mask  in  a  graphics  context XSetClipRectangles 

context  to  the/  XSetRegion:  set  clip_mask  of  the  graphics XSetRegion 

context  XSetClipMask:  set  clip_mask  pixmap  in  a  graphics XSetClipMask 

XSetaoseDownMode:  change  the  close  down  mode  of  a  client XSetCloseDownMode 

/a  read-only  colormap  cell  with  closest  hardware-supported  color XAllocColor 

/get  database  RGB  values  and  closest  hardware-supported  RGB/ XLookupColor 

/read/write  colormap  entry  to  the  closest  possible  hardware  color XStoreColor 

/of  read/write  colorcells  to  the  closest  possible  hardware  colors XStoreColors 

XQueryBestCursor:  get  the  closest  supported  cursor  sizes  XQueryBestCursor 

obtain  a  description  of  error  code  XGetErrorText: XGetErrorText 

with  closest  hardware-supported  color  /a  read-only  colormap  cell XAllocColor 

to  the  closest  possible  hardware  color  /read/write  colormap  entry  XStoreColor 

a  read-only  colorcell  from  color  name  /allocate  XAllocNamedColor 

RGB  values  from  color  name  /hardware-supported XLookupColor 

of  a  read/write  colorcell  by  color  name  /set  RGB  values XStoreNamedColor 

/look  up  RGB  values  from  ASCII  color  name  or  translate/ XParseColor 

XRecolorCursor:  change  the  color  of  a  cursor  XRecolorCursor 

read/write  (nonshareable)  color  planes  /allocate XAllocColorPlanes 

values  and  flags  for  a  specified  colorcell  /obtain  the  RGB  XQueryColor 

/set  RGB  values  of  a  read/write  colorcell  by  color  name  XStoreNamedColor 

/allocate  a  read-only  colorcell  from  color  name  XAllocNamedColor 

allocate  read/write  (nonshared)  colorcells  XAllocColorCells: XAllocColorCells 

RGB  values  for  an  array  of  colorcells  XQueryColors:  obtain XQueryColors 

/the  RGB  values  of  read/write  colorcells  to  the  closest/ XStoreColors 

XCreateColormap:  create  a  colormap XCreateColormap 

colormap  and  install  the  default  colormap  /delete  a  XFreeColormap 

XInstallColormap:  install  a  colormap XlnstallColormap 

XFreeColormap:  delete  a  colormap  and  install  the  default/ XFreeColormap 

XCopyColonmapAndFree:  copy  a  colormap  and  return  a  new/ XCopyColormapAndFree 

XSetWindowColormap:  set  the  colormap  attribute  for  a  window XSetWindowColormap 

/allocate  a  read-only  colormap  cell  with  closest/ XAllocColor 

XFreeColors:  free  colormap  cells  or  planes  XFreeColors 

/the  RGB  values  of  a  read/write  colormap  entry  to  the  closest/ XStoreColor 

/copy  a  colormap  and  return  a  new  colormap  ID XCopyColormapAndFree 

XUninstallColormap:  uninstall  a  colormap;  install  default  if  not/ XUninstallColormap 

/get  the  standard  colormap  property XGetStandardColormap 

/change  the  standard  colormap  property XSetStandardColormap 

/get  a  list  of  installed  colormaps  XListlnstalledColormaps 

to  the  closest  possible  hardware  colors  /of  read/write  colorcells  XStoreColors 

/load  a  resource  database  from  command  line  arguments XrmParseCommand 

/set  the  XA_WM_COMMAND  atom  (command  line  arguments) XSetCommand 

/set  the  graphics_exposures  component  in  a  graphics  context  XSetGraphicsExposures 

/set  the  line  drawing  components  in  a  graphics  context XSetLineAttributes 

Xlib's  GC/  XGetGCValues:  obtain  components  of  a  given  GC  from XGetGCValues 

context  XChangeGC:  change  the  components  of  a  given  graphics XChangeGC 

to  ASCT  string,  keysym,  and  ComposeStatus  /map  a  key  event XLookupString 

regions  XIntersectRegion:  compute  the  intersection  of  two XIntersectRegion 

XUnionRegion:  compute  the  union  of  two  regions XUnionRegion 

server  XOpenDisplay:  connect  a  client  program  to  an  X  XOpenDisplay 

XDrawLines:  draw  multiple  connected  lines XDrawLines 

control  list  to  allow  or  deny  connection  requests  /use  access XEnableAccessControl 
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/report  the  display  name  (when  connection  to  a  display  fails) XDisplayName 

XNoOp:  send  a  NoOp  to  exercise  connection  with  the  server XNoOp 

value  in  an/  XAddPixel:  add  a  constant  value  to  every  pixel XAddPixel 

drawable  into/  XGetLnage:  place  contents  of  a  rectangle  from XGetLnage 

XrmMcrgeDatabases:  merge  the  contents  of  one  database  into/ XnmMcrgcDatahascs 

components  of  a  given  graphics  context  XChangeGC:  change  the XChangcGC 

XCopyGC:  copy  a  graphics  context XCopyGC 

context  manager  (not  graphics  context)  /get  data  from  the XFindContext 

XFreeGC:  free  a  graphics  context XFreeGC 

with  the  specified  graphics  context  /ID)  associated XGContextFromGC 

and  context  type  (not  graphics  context)  /to  a  window XSaveContext 

set  the  arc  mode  in  a  graphics  context  XSetArcMode:  XSetArcMode 

pixel  value  in  a  graphics  context  /set  the  background XSetBackground 

clipjmask  pixmap  in  a  graphics  context  XSetClipMask:  set XSetClipMask 

the  clip  origin  in  a  graphics  context  XSetClipOrigin:  set XSetClipOrigin 

of  line  dashes  in  a  graphics  context  /set  a  pattern XSetDashes 

set  the  fill  rule  in  a  graphics  context  XSetFillRule: XSetFillRule 

set  the  fill  style  in  a  graphics  context  XSetFillStyle: XSetFillStyle 

the  current  font  in  a  graphics  context  XSetFont:  set XSetFont 

pixel  value  in  a  graphics  context  /set  the  foreground  XSetForeground 

logical  operation  in  a  graphics  context  /set  the  bitwise XSetFunction 

component  in  a  graphics  context  /the  graphics_exposures  XSetGraphicsExposures 

drawing  components  in  a  graphics  context  /set  the  line XSetLJneAttributes 

set  the  plane  mask  in  a  graphics  context  XSetPlaneMask: XSetPlaneMask 

and  plane  mask  in  a  graphics  context  /logical  function,  XSctState 

set  the  stipple  in  a  graphics  context  XSetStipple: XSetStipple 

the  sub  window  mode  in  a  graphics  context  XSetSubwindowMode:  set XSetSubwindowMode 

set  the  fill  tile  in  a  graphics  context  XSetTile: XSetTile 

origin  in  a  graphics  context  /set  the  tile/stipple XSetTSOrigin 

a  new  context  ID  (not  graphics  context)  XUniqueContext:  create XUniqueContext 

and/  XDeleteContext:  delete  a  context  entry  for  a  given  window  XDeleteContext 

XCreateGC:  create  a  new  graphics  context  for  a  given  screen  with/ XCreateGC 

XUniqueContext:  create  a  new  context  ID  (not  graphics/ XUniqueContext 

XFindContext:  get  data  from  the  context  manager  (not  graphics/ XFindContext 

/change  clip_mask  in  a  graphics  context  to  a  list  of  rectangles XSetClipRectangles 

/set  clip_mask  of  the  graphics  context  to  the  specified  region  XSetRegion 

/corresponding  to  a  window  and  context  type  (not  graphics/ XSaveContext 

disable  or  enable  access  control  XSetAccessControl:  XSetAccessControl 

mapping  of  modifier  keys  (Shift,  Control,  etc.)  /obtain  a XGetModifierMapping 

to  be  used  as  modifiers  (Shift,  Control,  etc.)  /set  keycodes XSetModifierMapping 

XBell:  ring  the  bell  (Control  G)  XBell 

add  a  host  to  the  access  control  list  XAddHost: XAddHost 

add  multiple  hosts  to  the  access  control  list  XAddHosts: XAddHosts 

remove  a  host  from  the  access  control  list  XRemoveHost:  XRemoveHost 

multiple  hosts  from  the  access  control  list  /remove XRemoveHosts 

XEnableAccessControl:  use  access  control  list  to  allow  or  deny/ XEnableAccessControl 

and  pointer/  XAllowEvents:  control  the  behavior  of  keyboard XAllowEvents 

XrmStringToBindingQuarkList:  convert  a  key  string  to  a/ XrmStringToBindingQuarkList 

list  XrmStringToQuarkList:  convert  a  key  string  to  a  quark XrmStringToQuarkUst 

XKeycodeToKeysym:  convert  a  keycode  to  a  keysym XKeycodeToKeysym 

a  keysym  XStringToKeysym:  convert  a  keysym  name  string  to  XStringToKeysym 

string  XKeysymToString:  convert  a  keysym  symbol  to  a XKeysymToString 

appropriate/  XKeysymToKeycode:  convert  a  keysym  to  the XKeysymToKeycode 

XrmQuarkToString:  convert  a  quark  to  a  string  XrmQuarkToString 

XrmStringToQuark:  convert  a  string  to  a  quark XrmStringToQuark 

window  to  another  /change  the  coordinate  system  from  one XTranslateCoordinates 

colormap/  XCopyColormapAndFree:  copy  a  colormap  and  return  a  new XCopyColormapAndFree 

XCopyGC:  copy  a  graphics  context XCopyGC 
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a  location  within/  XGetSublmage:  copy  a  rectangle  in  drawable  to XGetSublmage 

drawable  into  a/  XCopyPlane:  copy  a  single  plane  of  a  XCopyPlane 

XCopyArea:  copy  an  area  of  a  drawable XCopyArea 

XLookupKeysym:  get  the  keysym  corresponding  to  a  keycode  in/ XLookupKeysym 

XSaveContext:  save  a  data  value  corresponding  to  a  window  and/ XSaveContext 

format/  XCreateBitmapFromData:  create  a  bitmap  from  XI 1  bitmap  XCreateBitmapFromData 

XCreateColormap:  create  a  colormap XCreateColormap 

XCreateGlyphCursor:  create  a  cursor  from  font  glyphs  XCreateGlyphCursor 

standard/  XCreateFontCursor:  create  a  cursor  from  the  XCreateFontCursor 

XCreatePixmapCursor:  create  a  cursor  from  two  bitmaps XCreatePixmapCursor 

XrmGetStringDatabase:  create  a  database  from  a  string XrmGetStringDatabase 

mapping/  XNewModifiermap:  create  a  keyboard  modifier XNewModifiermap 

(X10)  XCreateAssocTable:  create  a  new  association  table  XCreateAssocTable 

graphics/  XUniqueContext:  create  a  new  context  ID  (not XUniqueContext 

XCreateRegion:  create  a  new  empty  region XCreateRegion 

for  a  given  screen/  XCreateGC:  create  a  new  graphics  context  XCreateGC 

XCreatePixmap:  create  a  pixmap  XCreatePixmap 

XCreatePixmapFromBitmapData:  create  a  pixmap  with  depth  from/ XCreatePixmapFromBitmapData 

an  image  XSublmage:  create  a  subimage  from  part  of XSublmage 

attributes  XCreateWindow:  create  a  window  and  set XCreate Window 

association  table  XMakeAssoc:  create  an  entry  in  an XMakeAssoc 

window  XCreateSimple Window:  create  an  unmapped  InputOutput XCreateSimple Window 

XGetWindow Attributes:  obtain  the  current  attributes  of  window XGetWindow Attributes 

context  XSetFont:  set  the  current  font  in  a  graphics XSetFont 

XGetFontPath:  get  the  current  font  search  path  XGetFontPath 

XGetGeometry:  obtain  the  current  geometry  of  drawable  XGetGeometry 

XGetlnputFocus:  return  the  current  keyboard  focus  window XGetlnputFocus 

/obtain  a  list  of  the  current  keyboard  preferences XGetKeyboardControl 

XQueryPointer:  get  the  current  pointer  location XQueryPointer 

XGetPointerControl:  get  the  current  pointer  preferences XGetPointerControl 

XGetScreenSaver:  get  the  current  screen  saver  parameters  XGetScreenSaver 

/obtain  a  bit  vector  for  the  current  state  of  the  keyboard XQueryKeymap 

XFreeCursor:  release  a  cursor  XFreeCursor 

change  the  color  of  a  cursor  XRecolorCursor: XRecolorCursor 

a  cursor  from  the  standard  cursor  font  /create XCreateFontCursor 

XUndefineCursor:  disassociate  a  cursor  from  a  window XUndefineCursor 

XCreateGlyphCursor:  create  a  cursor  from  font  glyphs  XCreateGlyphCursor 

XCreateFontCursor:  create  a  cursor  from  the  standard  cursor/ XCreateFontCursor 

XCreatePixmapCursor:  create  a  cursor  from  two  bitmaps XCreatePixmapCursor 

get  the  closest  supported  cursor  sizes  XQueryBestCursor:  XQueryBestCursor 

/obtain  the  "best"  supported  cursor,  tile,  or  stipple  size XQueryBestSize 

XDefineCursor:  assign  a  cursor  to  a  window XDefineCursor 

X10)  XDraw:  draw  a  polyline  or  curve  between  vertex  list  (from XDraw 

X10)  /draw  a  filled  polygon  or  curve  from  vertex  list  (from  XDrawFilled 

XFetchBuffer:  return  data  from  a  cut  buffer XFetchBuffer 

XStoreBuffer:  store  data  in  a  cut  buffer XStoreBuffer 

XFetchBytes:  return  data  from  cut  buffer  0  XFetchBytes 

XStoreBytes:  store  data  in  cut  buffer  0  XStoreBytes 

XRotateBuffers:  rotate  the  cut  buffers XRotateBuffers 

/set  a  pattern  of  line  dashes  in  a  graphics  context XSetDashes 

a  bitmap  from  XI 1  bitmap  format  data  /create  XCreateBitmapFromData 

a  pixmap  with  depth  from  bitmap  data,  /create XCreatePixmapFromBitmapData 

specified/  /free  the  in-memory  data  associated  with  the XFreeStringList 

XFetchBuffer:  return  data  from  a  cut  buffer XFetchBuffer 

XLookUpAssoc:  obtain  data  from  an  association  table XLookllpAssoc 

XFetchBytes:  return  data  from  cut  buffer  0 XFetchBytes 

(not  graphics/  XFindContext:  get  data  from  the  context  manager XFindContext 

XStoreBuffer:  store  data  in  a  cut  buffer XStoreBuffer 
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XStoreBytes:  store 

window  and/  XSaveContext:  save  a 

option  value  from  the  resource 

error  messages  from  the  error 

destroy  a  resource 

specification  to  a  resource 

specification  into  a  resource 

XrmGetFileDatabase:  retrieve  a 

XrmGetStringDatabase:  create  a 

XrmParseCommand:  load  a  resource 

/store  a  resource 

/merge  the  contents  of  one 

/return  a  list  of 

XLookupColor:  get 

/a  resource  specification  to  a 

a  resource  specification  into  a 

with  an  image  XDestroylmage: 

with  a  region  XDestroyRegion: 

or  disable  synchronization  for 

a  colormap  and  install  the 

given  user  geometry  string  and 

/uninstall  a  colormap;  install 

the  default/  XFreeColormap: 

given  window/  XDeleteContext: 

XDeleteProperty: 

association/  XDeleteAssoc: 

XDeleteModifiermapEntry: 

access  control  list  to  allow  or 

that  matches  the  desired 

a  drawable  into  a  drawable  with 

/create  a  pixmap  with 

/for  a  given  screen  with  the 

XListDepths:  determine  the 

XGetErrorText:  obtain  a 

information  that  matches  the 

remaining/  XKillClient: 

XrmDestroyDatabase: 

XDestroyWindow:  unmap  and 

window  XDestroySubwindows: 

modifier/  XFreeModifiermap: 

region  XPointlnRegion: 

in  a  region  XRectlnRegion: 

XEmptyRegion: 

the  same  size,/  XEqualRegion: 

on  a  given  screen  XListDepths: 

XXorRegion:  calculate  the 

XSetAccessControl: 

XSynchronize:  enable  or 

window  XUndefineCursor: 

an  X  server  and/  XCloseDisplay: 

XDrawSegments:  draw  multiple 

read  a  bitmap  from 

program  from  an  X  server  and 

of  hosts  having  access  to  this 

XFlush:  flush  the  request  buffer 

name  (when  connection  to  a 

a/  XDisplayName:  report  the 

XSetlconName:  set  the  name  to  be 


data  in  cut  buffer  0 

data  value  corresponding  to  a 

database  /extract  an  

database  /obtain  


XStoreBytes 

XSaveContext 

XGetDefault 

XGetErrorDatabaseText 

database.  XrmDestroyDatabase:  XrmDestroyDatabase 

database  /add  a  resource  XrmPutLineResource 

database  /store  a  resource  XrmPutResource 

database  from  a  file XrmGetFileDatabase 

database  from  a  string XrmGetStringDatabase 

database  from  command  line/ XrmParseCommand 

database  in  a  file XrmPutFileDatabase 

database  into  another XrmMergeDatabases 

database  levels XrmQGetSearchList 

database  RGB  values  and  closest/ XLookupColor 

database  using  a  quark  resource/ XrmQPutStringResource 

database  using  quarks  /store XrmQPutResource 

deallocate  memory  associated XDestroylmage 

deallocate  storage  associated XDestroyRegion 

debugging  XSynchronize:  enable  XSynchronize 

default  colormap  /delete XFreeColormap 

default  geometry  /geometry XGeometry 

default  if  not  already  installed XUninstallColormap 

delete  a  colormap  and  install XFreeColormap 

delete  a  context  entry  for  a  XDeleteContext 

delete  a  window  property  XDeleteProperty 

delete  an  entry  from  an XDeleteAssoc 

delete  an  entry  from  an/ XDeleteModifiermapEntry 

deny  connection  requests  /use XEnableAccessControl 

depth  and  class  /information XMatchVisuallnfo 

depth,  applying  pixel  values  /of XCopyPlane 

depth  from  bitmap  data XCreatePixmapFromBitmapData 

depth  of  the  specified  drawable  XCreateGC 

depths  available  on  a  given/ XListDepths 

description  of  error  code XGetErrorText 

desired  depth  and  class  /visual  XMatchVisuallnfo 

destroy  a  client  or  its XKillClient 

destroy  a  resource  database XrmDestroyDatabase 

destroy  a  window  and  all/ XDestroyWindow 

destroy  all  subwindows  of  a XDestroySubwindows 

destroy  and  free  a  keyboard  XFreeModifiermap 

determine  if  a  point  is  inside  a XPointlnRegion 

determine  if  a  rectangle  resides XRectlnRegion 

determine  if  a  region  is  empty XEmptyRegion 

determine  if  two  regions  have XEqualRegion 

determine  the  depths  available XListDepths 

difference  between  the  union  and/ XXorRegion 

disable  or  enable  access  control XSetAccessControl 

disable  synchronization  for/ XSynchronize 

disassociate  a  cursor  from  a XUndefineCursor 


disconnect  a  client  program  from 

disjoint  lines 

disk  XReadBitmapFile: 

display  /disconnect  a  client 

display  /obtain  a  list 


...  XCloseDisplay 
XDrawSegments 
XReadBitmapFile 
XCloseDisplay 
XlistHosts 
XFlush 
XDisplayName 


(display  all  queued  requests) 

display  fails)  /the  display  

display  name  (when  connection  to  XDisplayName 

displayed  in  a  window's  icon XSetlconName 
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XGetlconName:  get  the  name  to  be 

next  event  that  matches  mask; 

queue  that  matches  event  type; 

passed  window  and  passed  mask; 

stacking  order  of  children  up  or 

/change  the  close 

characters  XDrawImageStringl6: 

XDrawTextl6: 

XDrawImageString : 

XDrawText: 

from  vertex  list/  XDrawFilled: 
XDrawLine: 
XDrawPoint: 

vertex  list  (from  X10)  XDraw: 

foreground  only  XDrawString: 

rectangle  XDrawArc: 

pixmap  XPutlmage: 

XDrawRectangle: 

XDraw  Arcs: 

XDrawUnes: 

XDra  wSegments : 

XDrawPoints: 

rectangles  XDrawRectangles: 

XDrawStringl6: 

XCopyArea:  copy  an  area  of  a 

with  the  depth  of  the  specified 

obtain  the  current  geometry  of 

depth  J  /copy  a  single  plane  of  a 

contents  of  a  rectangle  from 

the/  /copy  a  rectangle  in 

/plane  of  a  drawable  into  a 

XSetLine Attributes:  set  the  line 

determine  if  a  region  is 

XCreateRegion:  create  a  new 

XSetAccessControl:  disable  or 

synchronization/  XSynchronize: 

generate  the  smallest  rectangle 

XClearWindow:  clear  an 

XDeleteContext:  delete  a  context 

XDeleteAssoc:  delete  an 

structure  /delete  an 

XMakeAssoc:  create  an 

structure  /add  a  new 

/values  of  a  read/write  colormap 

obtain  a  description  of 

/obtain  error  messages  from  the 

XSetErrorHandler:  set  a  nonfatal 

XGetErrorDatabaseText:  obtain 

/and  wait  for  all  events  and 

modifier  keys  (Shift,  Control, 

as  modifiers  (Shift,  Control, 

the  event  queue  for  a  matching 

XSendEvent:  send  an 

XPutBackEvent:  push  an 

set  a  nonfatal  error 

window  /return  the  next 

event  type;/  /return  the  next 

procedure/  XPeeklfEvent:  get  an 


displayed  in  an  icon  

don't  wait  /remove  the  

don't  wait  /the  next  event  in  ...... 

don't  wait  /event  matching  both 
down  /circulate  the 

down  mode  of  a  client 

draw  16-bit  image  text 

draw  1 6-bit  polytext  strings 

draw  8 -bit  image  text  characters  

draw  8-bit  polytext  strings 

draw  a  filled  polygon  or  curve 

draw  a  line  between  two  points 

draw  a  point 

draw  a  polyline  or  curve  between  .... 

draw  an  8-bit  text  string 

draw  an  arc  fitting  inside  a  

draw  an  image  on  a  window  or 

draw  an  outline  of  a  rectangle 

draw  multiple  arcs 

draw  multiple  connected  lines 

draw  multiple  disjoint  lines  

draw  multiple  points 

draw  the  outlines  of  multiple 

draw  two-byte  text  strings  

drawable 

drawable  /for  a  given  screen 

drawable  XGetGeometry: 

drawable  into  a  drawable  with  

drawable  into  an  image  /place  

drawable  to  a  location  within  

drawable  with  depth,  applying/ 

drawing  components  in  a  graphics/  . 

empty  XEmptyRegion:  

empty  region 

enable  access  control  

enable  or  disable 

enclosing  a  region  XQipBox:  

entire  window 

entry  for  a  given  window  and/  

entry  from  an  association  table 

entry  from  an  XModifierKeymap  .... 

entry  in  an  association  table  

entry  to  an  XModifierKeymap 

entry  to  the  closest  possible/ 

error  code  XGetErrorText: 

error  database 

error  event  handler 

error  messages  from  the  error/  

errors  to  be  processed  by  the/ 

etc.)  /obtain  a  mapping  of 

etc.)  /set  keycodes  to  be  used 

event  XChecklfEvent:  check 

event  back  on  the  input  queue 

event  handler  XSetErrorHandler:  .... 
event  in  queue  matching  type  and  ... 

event  in  queue  that  matches  

event  matched  by  predicate 


,  XGetlconName 

,  XCheckMaskEvent 

,  XCheckTypedEvent 

,  XCheckWindowEvent 

,  XCirculateSubwindows 

,  XSetCloseDownMode 

,  XDrawImageString  16 

,XDrawTextl6 

,  XDrawImageString 

,  XDrawText 

,  XDrawFilled 

.XDrawLine 

,  XDrawPoint 

.XDraw 

.  XDrawString 

.  XDrawArc 

.  XPutlmage 

.  XDrawRectangle 

.  XDrawArcs 

.  XDrawLines 

.  XDrawSegments 

.  XDrawPoints 

.  XDrawRectangles 

.XDrawString  16 

.  XCopyArea 

.  XCreateGC 

.  XGetGeometry 

.  XCopyPlane 

.  XGetlmage 

.  XGetSublmage 

.  XCopyPlane 

:  XSetLineAttributes 

.  XEmptyRegion 

.  XCreateRegion 

.  XSetAccessControl 

.  XSynchronize 

.  XClipBox 

.  XClearWindow 

.  XDeleteContext 

.  XDeleteAssoc 

.  XDeleteModifiermapEntry 

.  XMakeAssoc 

.  XInsertModifiermapEntry 

.  XStoreColor 

.  XGetErrorText 

.  XGetErrorDatabaseText 

.  XSetErrorHandler 

.  XGetErrorDatabaseText 

.XSync 

.  XGetModifierMapping 

.  XSetModifierMapping 

.  XChecklfEvent 

.  XSendEvent 

,  XPutBackEvent 

,  XSetErrorHandler 

,  XCheckTypedWindowEvent 

,  XCheckTypedEvent 

,  XPeeklfEvent 


Permuted  Index 


procedure  XlfEvent:  wait  for 

window  and/  /remove  the  next 

XNextEvent:  get  the  next 

the  number  of  events  in  the 

XChecklfEvent:  check  the 

XMaskEvent:  remove  the  next 

XCheckMaskEvent:  remove  the  next 

XWindowEvent:  remove  the  next 

and/  XLookupString:  map  a  key 

next  event  in  queue  that  matches 

window  XSelectlnput:  select  the 

the  queue  XPeekEvent:  get  an 

the  number  of  pending  input 

request  buffer  and  wait  for  all 

history/  XGetMotionEvents:  get 

/check  the  number  of 

/behavior  of  keyboard  and  pointer 

server  XNoOp:  send  a  NoOp  to 

XShrinkRegion:  reduce  or 

XQueryExtension:  get 

for  a  list  of  installed 

Xlib  and/  /return  a  list  of  all 

resource  database  XGetDefault: 

(when  connection  to  a  display 

XQueryBestTile:  obtain  the 

XQueryBestStipple:  obtain  the 

retrieve  a  database  from  a 

store  a  resource  database  in  a 

write  a  bitmap  to  a 

XFillPolygon: 

XFillRectangle: 

XFillArc: 

XLoadQueryFont:  load  a  font  and 

XFillArcs: 

XFillRectangles: 

XSetFillRule:setthe 

XSetFillStyle:  set  the 

XSetTilersetthe 

obtain  the  fastest  supported 

vertex  list/  XDrawFilled:  draw  a 

structures  that/  XGetVisuallnfo: 

XDrawArc:  draw  an  arc 

/obtain  the  RGB  values  and 

return  the  number  of/  XPending: 

wait  for  all  events  and/  XSync: 

(display  all  queued/  XFlush: 

return  the  current  keyboard 

XSetlnputFocus:  set  the  keyboard 

cursor  from  the  standard  cursor 

information  about  a  loaded 

XUnloadFont:  unload  a 

XLoadQueryFont:  load  a 

font/  XFreeFont:  unload  a 

create  a  cursor  from 

font  if  not  already  loaded;  get 

font  ID  XLoadFont:  load  a 

XSetFont:  set  the  current 

query  the  server  for  string  and 


event  matched  in  predicate 

event  matching  both  passed  

event  of  any  type  or  window 

event  queue  /check 

event  queue  for  a  matching  event 

event  that  matches  mask 

event  that  matches  mask;  don't/  ... 
event  that  matches  the  specified/  . 
event  to  ASCII  string,  keysym,  .... 

event  type;  don't  wait  /the 

event  types  to  be  sent  to  i 

event  without  removing  it  from  ........ 

events  /buffer  and  return 

events  and  errors  to  be/  /the 

events  from  pointer  motion  

events  in  the  event  queue 

events  when  these  resources  are/  .... 

exercise  connection  with  the  

expand  the  size  of  a  region 

extension  information 

extensions  /memory  allocated  

extensions  to  X  supported  by 

extract  an  option  value  from  the  

fails)  /report  the  display  name  

fastest  supported  fill  tile/ 

fastest  supported  stipple  shape 

file  XrmGetFileDatabase:  

file  XrmPutFileDatabase: 

file  XWriteBitmapFile: 

fill  a  polygon  

fill  a  rectangular  area  

fill  an  arc 

fill  information  structure 

fill  multiple  arcs 

fill  multiple  rectangular  areas 

fill  rule  in  a  graphics  context 

fill  style  in  a  graphics  context 

fill  tile  in  a  graphics  context 

fill  tile  shape  XQueryBestTile: 

filled  polygon  or  curve  from  

find  the  visual  information  

fitting  inside  a  rectangle 

flags  for  a  specified  colorcell 

flush  the  request  buffer  and 

flush  the  request  buffer  and 

flush  the  request  buffer 

focus  window  XGetlnputFocus: ... 

focus  window  

font  /create  a 

font  XQueryFont:  return 

font  and  fill  information/ 

font  and  free  storage  for  the  

font  glyphs  XCreateGlyphCursor: 

font  ID  XLoadFont:  load  a 

font  if  not  already  loaded;  get  

font  in  a  graphics  context  

font  metrics  XQueryTextExtents: . 


.  XlfEvent 

.  XCheckWindowEvent 

.  XNextEvent 

.  XEventsQueued 

.  XChecklfEvent 

.XMaskEvent 

.  XCheckMaskEvent 

.  XWindowEvent 

.  XLookupString 

.  XCheckTypedEvent 

,  XSelectlnput 

.  XPeekEvent 

.  XPending 

.XSync 

.  XGetMotionEvents 

.  XEventsQueued 

.  XAllowEvents 

.XNoOp 

.  XShrinkRegion 

.  XQueryExtension 

.  XFreeExtensionList 

.  XListExtensions 

.XGetDefault 

.  XDisplayName 

.  XQueryBestTile 

.  XQueryBestStipple 

.  XrmGetFileDatabase 

.  XrmPutFileDatabase 

.  XWriteBitmapFile 

.  XFillPolygon 

.  XFillRectangle 

.  XFillArc 

,  XLoadQueryFont 

,  XFillArcs 

,  XFillRectangles 

.XSetFillRule 

,  XSetFillStyle 

.XSetTile 

,  XQueryBestTile 

,  XDrawFilled 

,  XGetVisuallnfo 

,  XDrawArc 

,  XQueryColor 

,  XPending 

,  XSync 

,  XFlush 

,  XGetlnputFocus 

,  XSetlnputFocus 

,  XCreateFontCursor 

,  XQueryFont 

,  XUnloadFont 

,  XLoadQueryFont 

,  XFreeFont 

,  XCreateGlyphCursor 

,  XLoadFont 

,  XLoadFont 

,  XSetFont 

,  XQueryTextExtents 
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XTextExtents:  get  string  and   font  metrics  locally XTextExtents 

/query  the  server  for  string  and   font  metrics  of  a  16-bit/ XQueryTextExtentsl6 

XTextExtents  16:  get  string  and   font  metrics  of  a  16-bit/ XTextExtents  16 

return  a  list  of  the  available   font  names  XlistFonts: XUstFonts 

XGetFontProperty:  get  a   font  property  given  its  atom  XGetFontProperty 

XGetFontPath:  get  the  current   font  search  path  XGetFontPath 

XSetFontPath:  set  the   font  search  path  XSetFontPath 

a  font  and  free  storage  for  the   font  structure  /unload  XFreeFont 

and  information  about  loaded   fonts  /obtain  the  names  XListFontsWithlnfo 

function,/  XSetState:  set  the   foreground,  background,  logical XSetState 

draw  an  8-bit  text  string,   foreground  only  XDrawString:  XDrawString 

XSetForeground:  set  the   foreground  pixel  value  in  a/ XSetForeground 

/create  a  bitmap  from  XI 1  bitmap   format  data XCreateBitmapFromData 

the  atom  type  and  property   format  for  a  window  /obtain  XGetWindowProperty 

/obtain  the  supported  pixmap   formats  for  a  given  server XUstPixmapFormats 

XFreeGC:   free  a  graphics  context XFreeGC 

XFreeModifiermap:  destroy  and   free  a  keyboard  modifier  mapping/ XFreeModifiermap 

XFreePixmap:    free  a  pixmap  ID XFreePixmap 

XFreeColors:   free  colormap  cells  or  planes XFreeColors 

of/  XFreeExtensionList:   free  memory  allocated  for  a  list XFreeExtensionUst 

by  an  Xlib  function  XFree:    free  specified  memory  allocated  XFree 

XFreeFont:  unload  a  font  and   free  storage  for  the  font/ XFreeFont 

associated/  XFreeStringlist:   free  the  in-memory  data XFreeStringList 

XGetFontPath  XFreeFontPath:   free  the  memory  allocated  by XFreeFontPath 

XUstFonts.  XFreeFontNames:   free  the  memory  allocated  by XFreeFontNames 

XFreeFontlnfo:    free  the  memory  allocated  by/ XFreeFontlnfo 

association/  XDestroyAssocTable:   free  the  memory  allocated  for  an  XDestroyAssocTable 

allocate  memory  never  to  be   freed  Xpermalloc: Xpermalloc 

memory  allocated  by  an  Xlib  function  XFree:  free  specified XFree 

/foreground,  background,  logical   function,  and  plane  mask  in  a/ XSetState 

XSetAfterFunction:  set  a   function  called  after  all  Xlib/ XSetAfterFunction 

a  function  called  after  all  Xlib   functions  /set XSetAfterFunction 

XBell:  ring  the  bell  (Control   G) XBell 

of  a  given  GC  from  XHb's    GC  cache  /obtain  components XGetGCValues 

/obtain  components  of  a  given    GC  from  Xlib's  GC  cache  XGetGCValues 

XGContextFromGC:  obtain  the   GContext  (resource  ID)/ XGContextFromGC 

XPolygonRegion:    generate  a  region  from  points XPolygonRegion 

standard  window/  XParseGeometry:    generate  position  and  size  from  XParseGeometry 

enclosing  a  region  XClipBox:    generate  the  smallest  rectangle XClipBox 

user  geometry  string  and  default   geometry  /window  geometry  given XGeometry 

XGeometry:  calculate  window    geometry  given  user  geometry/ XGeometry 

XWMGeometry:  obtain  a  window's   geometry  information  XWMGeometry 

XGetGeometry:  obtain  the  current  geometry  of  drawable XGetGeometry 

and  size  from  standard  window   geometry  string  /position  XParseGeometry 

/window  geometry  given  user   geometry  string  and  default/ XGeometry 

atom  XGetFontProperty:    get  a  font  property  given  its XGetFontProperty 

XListlnstalledColormaps:   get  a  list  of  installed/ XListlnstaUedColormaps 

class  as/  XrmGetResource:    get  a  resource  from  name  and  XrmGetResource 

and  class  as/  XrmQGetResource:   get  a  resource  value  using  name XrmQGetResource 

given  its  atom  XGetAtomName:   get  a  string  name  for  a  property XGetAtomName 

property)  XFetchName:    get  a  window's  name  (XA_WM_NAME .  XFetchName 

predicate/  XPeeklfEvent:    get  an  event  matched  by  XPeeklfEvent 

from  the  queue  XPeekEvent:   get  an  event  without  removing  it XPeekEvent 

manager  (not/  XFindContext:    get  data  from  the  context XFindContext 

closest/  XLookupColor:    get  database  RGB  values  and XLookupColor 

history/  XGetMotionEvents:   get  events  from  pointer  motion XGetMotionEvents 

XQuery Extension:   get  extension  information XQuery Extension 

a  font  if  not  already  loaded;   get  font  ID  XLoadFont:  load  XLoadFont 
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XGetlconSizes:  get  preferred  icon  sizes XGetlconSizes 

locally  XTextExtents:  get  string  and  font  metrics XTextExtents 

1 6-bit/  XTextExtents  16:  get  string  and  font  metrics  of  a XTextExtents  1 6 

sizes  XQueryBestCursor:  get  the  closest  supported  cursor XQueryBestCursor 

XGetFontPath:  get  the  current  font  search  path XGetFontPath 

XQueryPointer:  get  the  current  pointer  location  XQueryPointer 

preferences  XGetPointerControl:  get  the  current  pointer XGetPointerControl 

parameters  XGetScreenSaver:  get  the  current  screen  saver XGetScreenSaver 

a  keycode  in/  XLookupKeysym:  get  the  keysym  corresponding  to XLookupKeysym 

an  icon  XGetlconName:  get  the  name  to  be  displayed  in XGetlconName 

or  window  XNextEvent:  get  the  next  event  of  any  type  XNextEvent 

XGetPointerMapping:  get  the  pointer  button  mapping  XGetPointerMapping 

window  XListProperties:  get  the  property  list  for  a XListProperties 

window  in/  XGetNormalHints:  get  the  size  hints  property  of  a  XGetNormalHints 

property  XGetStandardColormap:  get  the  standard  colormap XGetStandardColormap 

1 6-bit  character/  XTextWidth  16:  get  the  width  in  pixels  of  a XTextWidth  1 6 

8-bit  character/  XTextWidth:  get  the  width  in  pixels  of  an  XTextWidth 

a  window  XGetClassHint:  get  the  XA_WM_CLASS  property  of XGelClassHint 

property/  XGetTransientForHint:  get  the  XA_WM_TRANSIENT_FOR XGetTransientForHint 

create  a  cursor  from  font  glyphs  XCreateGlyphCurson XCreateGlyphCursor 

parameters  of  an  active  pointer  grab  /change  the XChangeActivePointerGrab 

release  a  button  from  a  passive  grab  XUngrabButton: XUngrabButton 

release  a  key  from  a  passive  grab  XUngrabKey: XUngrabKey 

the  keyboard  from  an  active  grab  XUngrabKeyboard:  release XUngrabKeyboard 

the  pointer  from  an  active  grab  XUngrabPointer:  release  XUngrabPointer 

release  the  server  from  grab  XUngrabServer: XUngrabServer 

XGrabKey:  grab  a  key  XGrabKey 

XGrabButton:  grab  a  pointer  button XGrabButton 

XGrabKeyboard:  grab  the  keyboard XGrabKeyboard 

XGrabPointer:  grab  the  pointer  XGrabPointer 

XGrabServer:  grab  the  server XGrabServer 

events  when  these  resources  are  grabbed  /of  keyboard  and  pointer XAllowEvents 

change  the  components  of  a  given  graphics  context  XChangeGC: XChangeGC 

XCopyGC:  copy  a  graphics  context  XCopyGC 

from  the  context  manager  (not  graphics  context)  /get  data XFindContext 

XFreeGC:  free  a  graphics  context XFreeGC 

associated  with  the  specified  graphics  context  /(resource  ID) XGContextFromGC 

a  window  and  context  type  (not  graphics  context)  Ao XSaveContext 

set  the  arc  mode  in  a  graphics  context  XSetArcMode: XSetArcMode 

the  background  pixel  value  in  a  graphics  context  /set XSetBackground 

set  clip_mask  pixmap  in  a  graphics  context  XSetClipMask: XSetClipMask 

/set  the  clip  origin  in  a  graphics  context  XSetClipOrigin 

a  pattern  of  line  dashes  in  a  graphics  context  /set XSetDashes 

set  the  fill  rule  in  a  graphics  context  XSetFillRule: XSetFillRule 

set  the  fill  style  in  a  graphics  context  XSetFillStyle: XSetFUlStyle 

set  the  current  font  in  a  graphics  context  XSetFont:  XSetFont 

the  foreground  pixel  value  in  a  graphics  context  /set XSetForeground 

bitwise  logical  operation  in  a  graphics  context  /set  the XSetFunction 

/component  in  a  graphics  context XSetGraphicsExposures 

the  line  drawing  components  in  a  graphics  context  /set XSetLineAttributes 

set  the  plane  mask  in  a  graphics  context  XSetPlaneMask:  XSetPlaneMask 

function,  and  plane  mask  in  a  graphics  context  /logical XSetState 

set  the  stipple  in  a  graphics  context  XSetStipple:  XSetStipple 

/set  the  subwindow  mode  in  a  graphics  context XSetSubwindowMode 

XSetTile:  set  the  fill  tile  in  a  graphics  context  XSetTile 

set  the  tile/supple  origin  in  a  graphics  context  XSetTSOrigin:  XSetTSOrigin 

/create  a  new  context  ID  (not  graphics  context) XUniqueContext 

screen/  XCreateGC:  create  a  new  graphics  context  for  a  given  XCreateGC 
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/change  clip_mask  in  a  graphics  context  to  a  list  of/ XSetClipRectangles 

XSctRegion:  set  clip_mask  of  the  graphics  context  to  the/ XSetRegion 

XSetGraphicsExposures:  set  the  graphics_exposures  component  in/ XSetGraphicsExposures 

set  a  nonfatal  error  event  handler  XSetErrorHandlen XSetErrorHandler 

entry  to  the  closest  possible  hardware  color  /colormap XStoreColor 

to  the  closest  possible  hardware  colors  /colorcells XStoreColors 

/colormap  cell  with  closest  hardware-supported  color XAllocColor 

/database  RGB  values  and  closest  hardware-supported  RGB  values/ XLookupColor 

/obtain  a  list  of  hosts  having  access  to  this  display  XListHosts 

ASCII  color  name  or  translate  hexadecimal  value  /values  from XParseColor 

read  the  window  manager  hints  property  XGetWMHints: XGetWMHints 

set  a  window  manager  hints  property  XSetWMHints: XSetWMHints 

XGetNormalHints:  get  the  size  hints  property  of  a  window  in/ XGetNormalHints 

XSetNormalHints:  set  the  size  hints  property  of  a  window  in/ XSetNormalHints 

XGetZoomHints:  read  the  size  hints  property  of  a  zoomed/ XGetZoomHints 

XSetZoomHints:  set  the  size  hints  property  of  a  zoomed/ XSetZoomHints 

/get  events  from  pointer  motion  history  buffer XGetMotionEvents 

allow  access  from  any  host  XDisableAccessControl: XDisableAccessControl 

list  XRemoveHosl:  remove  a  host  from  the  access  control XRemoveHost 

XAddHost:  add  a  host  to  the  access  control  list XAddHost 

XRemoveHosts:  remove  multiple  hosts  from  the  access  control/ XRemoveHosts 

XListHosts:  obtain  a  list  of  hosts  having  access  to  this/ XListHosts 

XAddHosts:  add  multiple  hosts  to  the  access  control  list XAddHosts 

the  name  to  be  displayed  in  an  icon  XGetlconName:  get  XGetlconName 

to  be  displayed  in  a  window's  icon  XSetlconName:  set  the  name  XSetlconName 

XGetlconSizes:  get  preferred  icon  sizes XGetlconSizes 

in  normal  state  (not  zoomed  or  iconified)  /property  of  a  window XGetNormalHints 

that  a  top-level  window  be  iconified  /request XlconifyWindow 

in  normal  state  (not  zoomed  or  iconified)  /property  of  a  window XSetNormalHints 

and  return  a  new  colormap  ID  /copy  a  colormap XCopyColormapAndFree 

XFreePixmap:  free  a  pixmap  ID XFreePixmap 

if  not  already  loaded;  get  font  ID  XLoadFont:  load  a  font XLoadFont 

/obtain  the  GContext  (resource  ID)  associated  with  the/ XGContextFromGC 

/obtain  the  visual  ID  from  a  Visual XVisuallDFrom Visual 

/create  a  new  context  ID  (not  graphics  context) XUniqueContext 

value  to  every  pixel  value  in  an  image  XAddPixel:  add  a  constant XAddPixel 

memory  associated  with  an  image  XDestroylmage:  deallocate  XDestroylmage 

rectangle  from  drawable  into  an  image  /place  contents  of  a XGetlmage 

a  single  pixel  value  from  an  image  XGetPixel:  obtain XGetPixel 

location  within  the  pre-existing  image  /in  drawable  to  a XGetSublmage 

set  a  pixel  value  in  an  image  XPutPixel: XPutPixel 

a  subimage  from  part  of  an  image  XSublmage:  create XSublmage 

XPutlmage:  draw  an  image  on  a  window  or  pixmap XPutlmage 

XDrawImageString:  draw  8-bit  image  text  characters  XDrawImageString 

XDrawImageStringl6:  draw  16-bit  image  text  characters  XDrawImageString  16 

XQueryExtension:  get  extension  information  XQueryExtension 

obtain  a  window's  geometry  information  XWMGeometry:  XWMGeometry 

XQueryFont:  return  information  about  a  loaded  font XQueryFont 

/obtain  the  names  and  information  about  loaded  fonts  XListFontsWithlnfo 

/load  a  font  and  fill  information  structure XLoadQueryFont 

XGetVisuallnfo:  find  the  visual  information  structures  that/ XGetVisuallnfo 

desired  depth/  /obtain  the  visual  information  that  matches  the XMatchVisuallnfo 

Xrmlnitialize:  initialize  the  resource  manager Xrmlnitialize 

the/  XFreeStringList:  free  the  in-memory  data  associated  with XFreeStringList 

and  return  the  number  of  pending  input  events  /the  request  buffer XPending 

push  an  event  back  on  the  input  queue  XPutBackEvent:  XPutBackEvent 

/create  an  unmapped  InputOutput  window XCreateSimple Window 

window  and  its/  XReparentWindow:  insert  a  window  between  another XReparentWindow 
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XDrawArc:  draw  an  arc  fitting  inside  a  rectangle XDrawArc 

determine  if  a  point  is  inside  a  region  XPointlnRegion: XPointlnRegion 

XInstallColormap:  install  a  colormap XListallColormap 

installed  /uninstall  a  colormap;  install  default  if  not  already XUninstallColormap 

/delete  a  colormap  and  install  the  default  colormap XFreeColormap 

install  default  if  not  already  installed  /uninstall  a  colormap; XUninstallColormap 

/get  a  list  of  installed  colormaps  XListlnstalledColormaps 

memory  allocated  for  a  list  of  installed  extensions  /free XFreeExtensionList 

XIntersectRegion:  compute  the  intersection  of  two  regions  XIntersectRegion 

difference  between  the  union  and  intersection  of  two  regions  /the  XXorRegion 

XGrabKey:  grab  a  key XGrabKey 

the  keyboard  preferences  such  as  key  click  /change XChangeKeyboardControl 

keysym,/  XLookupString:  map  a  key  event  to  ASCII  string, XLookupString 

XUngrabKey:  release  a  key  from  a  passive  grab XUngrabKey 

a  quark  list  /convert  a  key  string  to  a  binding  list  and  XrmStringToBindingQuarkList 

XrrnStringToQuarkList:  convert  a  key  string  to  a  quark  list XrmStringToQuarkList 

XGrabKeyboard:  grab  the  keyboard  XGrabKeyboard 

for  the  current  state  of  the  keyboard  /obtain  a  bit  vector XQueryKeymap 

these/  /control  the  behavior  of  keyboard  and  pointer  events  when  XAllowEvents 

XAutoRepeatOff :  turn  off  the  keyboard  auto-repeat  keys XAutoRepeatOff 

XAutoRepeatOn:  turn  on  the  keyboard  auto-repeat  keys XAutoRepeatOn 

/return  the  current  keyboard  focus  window XGetlnputFocus 

XSetlnputFocus:  set  the  keyboard  focus  window XSetlnputFocus 

XUngrabKeyboard:  release  the  keyboard  from  an  active  grab XUngrabKeyboard 

/change  the  keyboard  mapping  XChangeKeyboardMapping 

structure  /destroy  and  free  a  keyboard  modifier  mapping XFreeModifiermap 

XNewModifiermap:  create  a  keyboard  modifier  mapping/ XNewModifiermap 

/obtain  a  list  of  the  current  keyboard  preferences XGetKeyboardControl 

click  /change  the  keyboard  preferences  such  as  key  XChangeKeyboardControl 

a  keysym  to  the  appropriate  keycode  /convert  XKeysymToKeycode 

the  keysym  corresponding  to  a  keycode  in  structure  /get XLookupKeysym 

XKeycodeToKeysym:  convert  a  keycode  to  a  keysym XKeycodeToKeysym 

XRefreshKeyboardMapping:  read  keycode-keysym  mapping  from/ XRefreshKeyboardMapping 

return  symbols  for  keycodes  XGetKeyboardMapping: XGetKeyboardMapping 

/obtain  the  range  of  legal  keycodes  for  a  server XDisplayKeycodes 

XSetModifierMapping:  set  keycodes  to  be  used  as  modifiers/ XSetModifierMapping 

off  the  keyboard  auto-repeat  keys  XAutoRepeatOff:  turn XAutoRepeatOff 

turn  on  the  keyboard  auto-repeat  keys  XAutoRepeatOn:  XAutoRepeatOn 

/obtain  a  mapping  of  modifier  keys  (Shift,  Control,  etc.) XGetModifierMapping 

convert  a  keycode  to  a  keysym  XKeycodeToKeysym: XKeycodeToKeysym 

a  keysym  name  string  to  a  keysym  XStringToKeysym:  convert XStringToKeysym 

/map  a  key  event  to  ASCII  string,  keysym,  and  ComposeStatus XLookupString 

keycode/  XLookupKeysym:  get  the  keysym  corresponding  to  a XLookupKeysym 

XStringToKeysym:  convert  a  keysym  name  string  to  a  keysym XStringToKeysym 

XKeysymToString:  convert  a  keysym  symbol  to  a  string XKeysymToString 

XRebindKeysym:  rebind  a  keysym  to  a  string  for  client XRebindKeysym 

XKeysymToKeycode:  convert  a  keysym  to  the  appropriate/ XKeysymToKeycode 

/obtain  the  range  of  legal  keycodes  for  a  server XDisplayKeycodes 

return  a  list  of  database  levels  XrmQGetSearchList: XrmQGetSearchList 

a  resource  database  from  command  line  arguments  /load XrmParseCommand 

the  XA_WM_COMMAND  atom  (command  line  arguments)  /set  XSetCommand 

XDrawLine:  draw  a  line  between  two  points XDrawLine 

XSetDashes:  set  a  pattern  of  line  dashes  in  a  graphics/ XSetDashes 

XSetLine  Attributes:  set  the  line  drawing  components  in  a/ XSetLineAttributes 

draw  multiple  connected  lines.  XDrawLines: XDrawLines 

draw  multiple  disjoint  lines  XDrawSegments: XDrawSegments 

add  a  host  to  the  access  control  list  XAddHost: XAddHost 

hosts  to  the  access  control  list  XAddHosts:  add  multiple  XAddHosts 
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with  the  specified  string  list  /in-memory  data  associated  XFreeStringList 

a  host  from  the  access  control  list  XRemoveHost:  remove XRemoveHost 

hosts  from  the  access  control  list  /remove  multiple XRemoveHosts 

to  a  binding  list  and  a  quark  list  /convert  a  key  string XrmStringToBindingQuarkList 

convert  a  key  string  to  a  quark  list  XrmStringToQuarkList: XrmStringToQuarkList 

a  key  string  to  a  binding  list  and  a  quark  list  /convert XrmStringToBindingQuarkList 

/search  prepared  list  for  a  given  resource XrmQGetSearchResource 

/get  the  property  list  for  a  window XListProperties 

polyline  or  curve  between  vertex  list  (from  XI 0)  XDraw:  draw  a XDraw 

polygon  or  curve  from  vertex  list  (from  X10)  /draw  a  filled XDrawFilled 

XListExtensions:  return  a  list  of  all  extensions  to  X/ XListExtensions 

root  XQueryTree:  return  a  list  of  children,  parent,  and XQueryTree 

XrmQGetSearchList:  return  a  list  of  database  levels  XrmQGetSearchList 

this/  XListHosts:  obtain  a  list  of  hosts  having  access  to  XListHosts 

XListlnstalledColormaps:  get  a  list  of  installed  colormaps XListlnstalledColormaps 

/free  memory  allocated  for  a  list  of  installed  extensions XFreeExtensionUst 

in  a  graphics  context  to  a  list  of  rectangles  /clip_mask  XSetClipRectangles 

XTextProperty/  /obtain  a  list  of  strings  from  a  specified  XTextPropertyToStringList 

XTextProperty/  /set  the  specified  list  of  strings  to  an XStringListToTextProperty 

XListFonts:  return  a  list  of  the  available  font  names XListFonts 

XGetKeyboardControl:  obtain  a  list  of  the  current  keyboard/ XGetKeyboardControl 

requests  /use  access  control  list  to  allow  or  deny  connection XEnableAccessControl 

structure  XLoadQueryFont:  load  a  font  and  fill  information  XLoadQueryFont 

loaded;  get  font  ID  XLoadFont:  load  a  font  if  not  already XLoadFont 

command  line/  XrmParseCommand:  load  a  resource  database  from XrmParseCommand 

return  information  about  a  loaded  font  XQueryFont: XQueryFont 

the  names  and  information  about  loaded  fonts  /obtain XListFonts Withlnfo 

load  a  font  if  not  already  loaded;  get  font  ID  XLoadFont:  XLoadFont 

get  string  and  font  metrics  locally  XTextExtents: XTextExtents 

of  a  16-bit  character  string,  locally  /string  and  font  metrics  XTextExtents  16 

of  an  8-bit  character  string,  locally  /get  the  width  in  pixels XTextWidth 

of  a  16-bit  character  string,  locally  /get  the  width  in  pixels XTextWidth  16 

get  the  current  pointer  location  XQueryPointer:  XQueryPointer 

/a  rectangle  in  drawable  to  a  location  within  the  pre-existing/ XGetSublmage 

/set  the  foreground,  background,  logical  function,  and  plane  mask/ XSetState 

XSetFunction:  set  the  bitwise  logical  operation  in  a  graphics/ XSetFunction 

color  name  or/  XParseColor:  look  up  RGB  values  from  ASCII XParseColor 

order  XLowerWindow:  lower  a  window  in  the  stacking XLowerWindow 

initialize  the  resource  manager  Xrmlnitialize:  Xrmlnitialize 

set  of  properties  for  the  window  manager  /set  the  minimum XSetStandardProperties 

name  to  a  window  for  the  window  manager  XStoreName:  assign  a  XStoreName 

XGetWMHints:  read  the  window  manager  hints  property XGetWMHints 

XSetWMHints:  set  a  window  manager  hints  property XSetWMHints 

/get  data  from  the  context  manager  (not  graphics  context) XFindContext 

/set  a  window's  standard  window  manager  properties XSetWMProperties 

keysym,  and/  XLookupString:  map  a  key  event  to  ASCII  string XLookupString 

XMapWindow:  map  a  window  XMap Window 

siblings  XMapRaised:  map  a  window  on  top  of  its  XMapRaised 

XMapSub windows:  map  all  subwindows  of  window XMapSubwindows 

change  the  keyboard  mapping  XChangeKeyboardMapping: ...  XChangeKeyboardMapping 

get  the  pointer  button  mapping  XGetPointerMapping: XGetPointerMapping 

set  the  pointer  button  mapping  XSetPointerMapping: XSetPointerMapping 

/read  keycode-keysym  mapping  from  server  into  Xlib XRefreshKeyboardMapping 

XGetModifierMapping:  obtain  a  mapping  of  modifier  keys  (Shift,/ XGetModifierMapping 

and  free  a  keyboard  modifier  mapping  structure  /destroy  XFreeModifiermap 

/create  a  keyboard  modifier  mapping  structure XNewModifiermap 

the  next  event  that  matches  mask  XMaskEvent:  remove XMaskEvent 

event  that  matches  the  specified  mask  and  window  /remove  the  next XWindowEvent 
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the  next  event  that  matches 

both  passed  window  and  passed 

XSetPlaneMask:  set  the  plane 

/logical  function,  and  plane 

/information  structures  that 

XPeeklfEvent:  get  an  event 

XlfEvent:  wait  for  event 

/the  next  event  in  queue  that 

remove  the  next  event  that 

/remove  the  next  event  that 

/the  visual  information  that 

/remove  the  next  event  that 

passed/  /remove  the  next  event 

check  the  event  queue  for  a 

/return  the  next  event  in  queue 

function  XFree:  free  specified 

XFreeFontPath:  free  the 

XFreeFontNames:  free  the 

XFreeFontlnfo:  free  the 

XFreeExtensionList:  free 

XDestroyAssocTable:  free  the 

XDestroy Image:  deallocate 

XCreatelmage:  allocate 

Xpermalloc:  allocate 

database/  XrmMergeDatabases: 

/obtain  error 

the  server  for  string  and  font 

get  string  and  font 

/the  server  for  string  and  font 

stringy  /get  string  and  font 

XSetStandardProperties:  set  the 

XSetArcMode:  set  the  arc 

/set  the  subwindow 

/change  the  close  down 

etc.)  /obtain  a  mapping  of 

/destroy  and  free  a  keyboard 

/create  a  keyboard 

/set  keycodes  to  be  used  as 

/get  events  from  pointer 

XMoveWindow: 

point  on  the/  XWarpPointer: 

XDrawArcs:  draw 

XFillArcs:  fill 

XDrawLines:  draw 

XDrawSegments:  draw 

control/  XRemoveHosts:  remove 

control  list  XAddHosts:  add 

XDrawPoints:  draw 

/draw  the  outlines  of 

XFillRectangles:  fill 

a  read-only  colorcell  from  color 

RGB  values  from  color 

a  read/write  colorcell  by  color 

/get  a  resource  value  using 

/get  a  resource  from 

database  using  a  quark  resource 

with  separate  resource 

Uom  XGetAtomName:  get  a  string 


mask;  don't  wait  /remove , 
mask;  don't  wait  /event  matching 
mask  in  a  graphics  context  ............ 

mask  in  a  graphics  context 

match  the  specified  template , 

matched  by  predicate  procedure/ , 

matched  in  predicate  procedure 

matches  event  type;  don't  wait 

matches  mask  XMaskEvent: , 

matches  mask;  don't  wait 

matches  the  desired  depth  and/ , 

matches  the  specified  mask  and/ 

matching  both  passed  window  and  .... 

matching  event  XChecklfEvent: 

matching  type  and  window  

memory  allocated  by  an  Xlib 

memory  allocated  by  XGetFontPath  . 

memory  allocated  by  XUstFonts 

memory  allocated  by/ 

memory  allocated  for  a  list  of/ 

memory  allocated  for  an/ 

memory  associated  with  an  image 

memory  for  an  Xlmage  structure 

memory  never  to  be  freed 

merge  the  contents  of  one 

messages  from  the  error  database  

metrics  /Query 

metrics  locally  XTextExtents: 

metrics  of  a  16-bit  character/ 

metrics  of  a  16-bit  character 

minimum  set  of  properties  for/ 

mode  in  a  graphics  context 

mode  in  a  graphics  context 

mode  of  a  client 

modifier  keys  (Shift,  Control, 

modifier  mapping  structure 

modifier  mapping  structure 

modifiers  (Shift,  Control,  etc.)  

motion  history  buffer 

move  a  window 

move  the  pointer  to  another 

multiple  arcs 

multiple  arcs  

multiple  connected  lines 

multiple  disjoint  lines 

multiple  hosts  from  the  access  

multiple  hosts  to  the  access  

multiple  points 

multiple  rectangles 

multiple  rectangular  areas 

name  XAllocNamedColor:  allocate  .. 
name  /closest  hardware-supported  .... 

name  /set  RGB  values  of 

name  and  class  as  quarks 

name  and  class  as  strings 

name  and  string  value  Ao  a 

name  and  value  /specification  

name  for  a  property  given  its 


,  XCheckMaskEvent 

.  XCheckWindowEvent 

.  XSetPlaneMask 

.XSetState 

.XGetVisuallnfo 

.  XPeeklfEvent 

.  XlfEvent 

.  XCheckTypedEvent 

.  XMaskEvent 

.  XCheckMaskEvent 

.  XMatchVisuallnfo 

.  XWindowEvent 

.XCheckWindowEvent 

.  XChecklfEvent 

.  XCheckTypedWindowEvent 

.XFree 

.  XFreeFontPath 

.  XFreeFontNames 

.  XFreeFontlnfo 

.  XFreeExtensionList 

.  XDestroyAssocTable 

.  XDestroylmage 

.  XCreatelmage 

.  Xpermalloc 

.  XrmMergeDatabases 

.  XGetErrorDatabaseText 

.  XQueryTextExtents 

.  XTextExtents 

.  XQueryTextExtents  1 6 

.XTextExtents  16 

.  XSetStandardProperties 

.  XSetArcMode 

.  XSetSubwindowMode 

.  XSetCloseDownMode 

.  XGetModifierMapping 

.  XFreeModifiermap 

,  XNewModifiermap 

.  XSetModifierMapping 

,  XGetMotionEvents 

.  XMoveWindow 

.  XWarpPointer 

.  XDrawArcs 

.  XFillArcs 

,  XDrawLines 

.  XDrawSegments 

.  XRemoveHosts 

.  XAddHosts 

.  XDrawPoints 

,  XDrawRectangles 

.  XFillRectangles 

.  XAllocNamedColor 

.  XLookupColor 

.  XStoreNamedColor 

.  XrmQGetResource 

.  XrmGetResource 

.  XrmQPutStringResource 

,  XrmPutStringResource 

,  XGetAtomName 
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/up  RGB  values  from  ASCII  color  name  or  translate  hexadecimal/ XParseColor 

an  atom  for  a  given  property  name  string  XInternAtom:  return XInternAtom 

/convert  a  keysym  name  string  to  a  keysym XStringToKeysym 

manager  XStoreName:  assign  a  name  to  a  window  for  the  window XStoreName 

window's/  XSetlconName:  set  the  name  to  be  displayed  in  a  XSetlconName 

XGetlconName:  get  the  name  to  be  displayed  in  an  icon XGetlconName 

XDisplayName:  report  the  display  name  (when  connection  to  a/ XDisplayName 

XFetchName:  get  a  window's  name  (XA_WM_NAME  property) XFetchName 

a  list  of  the  available  font  names  XlistFonts:  return XUstFonts 

XUstFontsWithlnfo:  obtain  the  names  and  information  about/ XListFontsWithlnfo 

Xpermalloc:  allocate  memory  never  to  be  freed Xpermalloc 

XCreateAssocTable:  create  a  new  association  table  (X10) XCreateAssocTable 

/copy  a  colormap  and  return  a  new  colormap  ID XCopyColormapAndFree 

XUniqueContext:  create  a  new  context  ID  (not  graphics/ XUniqueContext 

XCreateRegion:  create  a  new  empty  region XCreateRegion 

XInsertModifiermapEntry:  add  a  new  entry  to  an  XModifierKeymap/ XlnsertModifiermapEntry 

screen  with/  XCreateGC:  create  a  new  graphics  context  for  a  given  XCreateGC 

XrmUniqueQuark:  allocate  a  new  quark  XrmUniqueQuark 

type  and  window  /return  the  next  event  in  queue  matching XCheckTypedWindowEvent 

XCheckTypedEvent:  return  the  next  event  in  queue  that  matches/ XCheckTypedEvent 

XCheckWindowEvent:  remove  the  next  event  matching  both  passed/ XCheckWindowEvent 

XNextEvent:  get  the  next  event  of  any  type  or  window XNextEvent 

XMaskEvent:  remove  the  next  event  that  matches  mask XMaskEvent 

XCheckMaskEvent:  remove  the  next  event  that  matches  mask;/ XCheckMaskEvent 

XWindowEvent:  remove  the  next  event  that  matches  the/ XWindowEvent 

XSetErrorHandler:  set  a  nonfaial  error  event  handler XSetErrorHandler 

/allocate  read/write  (nonshareable)  color  planes X  AllocColorPlanes 

/allocate  read/write  (nonshared)  colorcells XAllocColorCells 

the  server  XNoOp:  send  a  NoOp  to  exercise  connection  with XNoOp 

/hints  property  of  a  window  in  normal  state  (not  zoomed  or/ XGetNormalHints 

/hints  property  of  a  window  in  normal  state  (not  zoomed  or/ XSetNormalHinls 

a  colormap;  install  default  if  not  already  installed  /uninstall XUninstallColormap 

XLoadFont:  load  a  font  if  not  already  loaded;  get  font  ID XLoadFont 

data  from  the  context  manager  (not  graphics  context)  /get XFindContext 

/to  a  window  and  context  type  (not  graphics  context) XSaveContext 

/create  a  new  context  ID  (not  graphics  context)  XUniqueContext 

/of  a  window  in  normal  state  (not  zoomed  or  iconified) XGetNormalHints 

/of  a  window  in  normal  state  (not  zoomed  or  iconified) XSetNormalHints 

queue  XEventsQueued:  check  the  number  of  events  in  the  event  XEventsQueued 

/request  buffer  and  return  the  number  of  pending  input  events XPending 

current  state  of/  XQueryKeymap:  obtain  a  bit  vector  for  the XQueryKeymap 

code  XGetErrorText:  obtain  a  description  of  error XGetErrorText 

access  to  this/  XListHosts:  obtain  a  list  of  hosts  having XListHosts 

XTextPropertyToStringLJst:  obtain  a  list  of  strings  from  a/ XTextPropertyToStringLJst 

keyboard/  XGetKeyboardControl:  obtain  a  list  of  the  current XGetKeyboardControl 

keys/  XGetModifierMapping:  obtain  a  mapping  of  modifier XGetModifierMapping 

an  image  XGetPixel:  obtain  a  single  pixel  value  from XGetPixel 

information  XWMGeometry:  obtain  a  window's  geometry XWMGeometry 

from  Xlib's  GC/  XGetGCValues:  obtain  components  of  a  given  GC XGetGCValues 

table  XLookUpAssoc:  obtain  data  from  an  association XLookUpAssoc 

error/  XGetErrorDatabaseText:  obtain  error  messages  from  the XGetErrorDatabaseText 

of  colorcells  XQueryColors:  obtain  RGB  values  for  an  array XQueryColors 

property/  XGetWindowProperty:  obtain  the  atom  type  and XGetWindowProperty 

cursor,  tile,/  XQueryBestSize:  obtain  the  "best"  supported  XQueryBestSize 

window  XGetWindow Attributes:  obtain  the  current  attributes  of XGetWindow Attributes 

drawable  XGetGeometry:  obtain  the  current  geometry  of XGetGeometry 

fill  tile  shape  XQueryBestTile:  obtain  the  fastest  supported XQueryBestTile 

stipple/  XQueryBestStipple:  obtain  the  fastest  supported XQueryBestStipple 
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ID)  associated/  XGContextFromGC:  obtain  the  GContext  (resource  XGContextFromGC 

about/  XlistFontsWithlnfo:  obtain  the  names  and  information XListFontsWithlnfo 

key  codes  for/  XDisplayKeycodes:  obtain  the  range  of  legal XDisplayKeycodes 

for  a  specified/  XQueryColor:  obtain  the  RGB  values  and  flags XQueryColor 

formats  for/  XListPixmapFormats:  obtain  the  supported  pixmap XListPixmapFormats 

Visual  XVisuallDFrom Visual:  obtain  the  visual  ID  from  a XVisuallDFrom Visual 

that  matches/  XMatchVisuallnfo:  obtain  the  visual  information XMatchVisuallnfo 

structure/  XGetRGBColormaps:  obtain  the  XStandardColormap XGetRGBColormaps 

turn  the  screen  saver  on  or  off  XForceScreenSaver: XForceScreenSaver 

keys  XAutoRepeatOff :  turn  off  the  keyboard  auto-repeat XAutoRepeatOff 

two  regions  have  the  same  size,  offset,  and  shape  /determine  if XEqualRegion 

XOffsetRegion:  change  offset  of  a  region  XOffsetRegion 

an  8-bit  text  string,  foreground  only  XDrawString:  draw XDrawString 

/set  the  bitwise  logical  operation  in  a  graphics  context XSetFunction 

XGetDefault:  extract  an  option  value  from  the  resource/ XGetDefault 

child  to  the  top  of  the  stacking  order  /circulate  the  bottom XCirculaleSubwindowsDown 

to  the  bottom  of  the  stacking  order  /circulate  the  top  child XCirculateSubwindowsUp 

size,  border  width,  or  stacking  order  /the  window  position, XConfigureWindow 

lower  a  window  in  the  stacking  order  XLowerWindow: XLowerWindow 

to  the  top  of  the  stacking  order  /raise  a  window XRaise Window 

/circulate  the  stacking  order  of  children  up  or  down XCirculateSubwindows 

/change  the  stacking  order  of  siblings XRestack  Windows 

XSetClipOrigin:  set  the  clip  origin  in  a  graphics  context XSetClipOrigin 

/set  the  tile/stipple  origin  in  a  graphics  context XSetTSOrigin 

XDrawRectangle:  draw  an  outline  of  a  rectangle XDrawRectangle 

XDrawRectangles:  draw  the  outlines  of  multiple  rectangles  XDrawRectangles 

XGetSelectionOwner:  return  the  owner  of  a  selection XGetSelectionOwner 

XSetSelectionOwner:  set  the  owner  of  a  selection  XSetSelectionOwner 

get  the  current  screen  saver  parameters  XGetScreenSaver: XGetScreenSaver 

grab  /change  the  parameters  of  an  active  pointer XChangeActivePointerGrab 

XSetScreenSaver:  set  the  parameters  of  the  screen  saver XSetScreenSaver 

between  another  window  and  its  parent  /insert  a  window XReparentWindow 

return  a  list  of  children,  parent,  and  root  XQueryTree: XQueryTree 

create  a  subimage  from  part  of  an  image  XSublmage: XSuhlmage 

matching  both  passed  window  and  passed  mask;  don't  wait  /event XCheckWindowEvent 

/the  next  event  matching  both  passed  window  and  passed  mask;/ XCheckWindowEvent 

release  a  button  from  a  passive  grab  XUngrabButton:  XUngrabButton 

XUngrabKey:  release  a  key  from  a  passive  grab XUngrabKey 

get  the  current  font  search  path  XGetFontPath: XGetFontPath 

set  the  font  search  path  XSetFontPath:  XSetFontPath 

graphics/  XSetDashes:  set  a  pattern  of  line  dashes  in  a  XSetDashes 

buffer  and  return  the  number  of  pending  input  events  /request XPending 

repaint/  /change  a  window  border  pixel  value  attribute  and  XSetWindowBorder 

window  /set  the  background  pixel  value  attribute  of  a XSetWindowBackground 

XGetPixel:  obtain  a  single  pixel  value  from  an  image XGetPixel 

context  /set  the  background  pixel  value  in  a  graphics XSetBackground 

context  /set  the  foreground  pixel  value  in  a  graphics XSetForeground 

/add  a  constant  value  to  every  pixel  value  in  an  image XAddPixel 

XPutPixel:  set  a  pixel  value  in  an  image XPutPixel 

a  drawable  with  depth,  applying  pixel  values  /of  a  drawable  into XCopyPlane 

XTextWidthl6:  get  the  width  in  pixels  of  a  16-bit  character/ XTextWidthl6 

XTextWidth:  get  the  width  in  pixels  of  an  8-bit  character/ XTextWidth 

XCreatePixmap:  create  a  pixmap XCreatePixmap 

draw  an  image  on  a  window  or  pixmap  XPutlmage:  XPutlmage 

server  /obtain  the  supported  pixmap  formats  for  a  given  XListPixmapFormats 

XFreePixmap:  free  a  pixmap  ID XFreePixmap 

XSetClipMask:  set  clip_mask  pixmap  in  a  graphics  context XSetClipMask 

data,  /create  a  pixmap  with  depth  from  bitmap XCreatePixmapFromBitmapData 
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from  drawable  into/  XGetlmage:   place  contents  of  a  rectangle XGetlmage 

XSetPlaneMask:  set  the   plane  mask  in  a  graphics  context XSetPlaneMask 

/logical  function,  and   plane  mask  in  a  graphics  context XSetState 

XCopyPlane:  copy  a  single   plane  of  a  drawable  into  a/ XCopyPlane 

read/write  (nonshareable)  color   planes  /allocate  XAllocColorPlanes 

free  colormap  cells  or  planes  XFreeColors: XFreeColors 

XDrawPoint:  draw  a   point XDrawPoint 

XPointlnRegion:  determine  if  a   point  is  inside  a  region XPointlnRegion 

/move  the  pointer  to  another  point  on  the  screen XWarpPointer 

XGrabPointer:  grab  the   pointer XGrabPointer 

XGrabButton:  grab  a  pointer  button  XGrabButton 

XGetPointerMapping:  get  the   pointer  button  mapping XGetPointerMapping 

XSetPointerMapping:  set  the   pointer  button  mapping XSetPointerMapping 

/the  behavior  of  keyboard  and   pointer  events  when  these/ XAllowEvents 

XUngrabPointer:  release  the   pointer  from  an  active  grab  XUngrabPointer 

the  parameters  of  an  active   pointer  grab  /change XChangeActivePointerGrab 

XQueryPointer:  get  the  current  pointer  location XQueryPointer 

/get  events  from   pointer  motion  history  buffer XGetMotionEvents 

/change  the   pointer  preferences XChangePointerControl 

/get  the  current   pointer  preferences XGetPointerControl 

screen  XWarpPointer:  move  the   pointer  to  another  point  on  the XWarpPointer 

draw  a  line  between  two   points  XDrawLine: XDrawLJne 

XDrawPoints:  draw  multiple   points XDrawPoints 

generate  a  region  from   points  XPolygonRegion: XPolygonRegion 

XFillPolygon:  fill  a   polygon XFillPolygon 

list/  XDrawFilled:  draw  a  filled   polygon  or  curve  from  vertex XDrawFilled 

list  (from  X10)  XDraw:  draw  a   polyline  or  curve  between  vertex XDraw 

XDrawText:  draw  8-bit   polylext  strings XDrawText 

XDrawTextl6:  draw  16-bit   polytext  strings XDrawTextl6 

window/  XParseGeometry:  generate   position  and  size  from  standard  XParseGeometry 

/change  the  size  and   position  of  a  window XMoveResize Window 

stacking/  /change  the  window   position,  size,  border  width,  or XConfigu  re  Window 

/colormap  entry  to  the  closest  possible  hardware  color XStoreColor 

/colorcells  to  the  closest  possible  hardware  colors  XStoreColors 

wait  for  event  matched  in   predicate  procedure  XlfEvent:  XlfEvent 

/get  an  event  matched  by   predicate  procedure  without/ XPeeklfEvent 

to  a  location  within  the   pre-existing  image  fm  drawable  XGetSublmage 

/change  the  pointer  preferences XChangePointerControl 

a  list  of  the  current  keyboard   preferences  /obtain  XGetKeyboardControl 

get  the  current  pointer   preferences  XGetPointerControl: XGetPointerControl 

/change  the  keyboard   preferences  such  as  key  click XChangeKeyboardControl 

XGetlconSizes:  get  preferred  icon  sizes  XGetlconSizes 

XrmQGetSearchResource:  search   prepared  list  for  a  given/ XrmQGetSearchResource 

for  event  matched  in  predicate   procedure  XlfEvent:  wait XlfEvent 

/an  event  matched  by  predicate   procedure  without  removing  it/ XPeeklfEvent 

for  all  events  and  errors  to  be   processed  by  the  server  /wait XSync 

display  /disconnect  a  client  program  from  an  X  server  and  XCloseDisplay 

XOpenDisplay:  connect  a  client  program  to  an  X  server XOpenDisplay 

read  one  of  a  window's  text   properties  XGetTextProperty: XGetTextProperty 

set  one  of  a  window's  text  properties  XSetTextProperty: XSetTextProperty 

window's  standard  window  manager   properties  /set  a XSetWMProperties 

/rotate  properties  in  the   properties  array XRotateWindowProperties 

manager  /set  the  minimum  set  of  properties  for  the  window XSetStandardProperties 

XRotateWindowProperties:  rotate   properties  in  the  properties/ XRotateWindowProperties 

XDeleteProperty:  delete  a  window   property XDeleteProperty 

get  a  window's  name  (XA_WM_NAME  property)  XFetchName: XFetchName 

associated  with  the  specified   property  /structure  XGetRGBColormaps 

get  the  standard  colormap   property  XGetStandardColormap: XGetStandardColormap 
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read  the  window  manager  hints 

read  a  window's  XA_WM_ICON_NAME 

read  a  window's  XA_WM_NAME 

a  window's  XA_WM_NORMAL_HINTS 

read  a  window's  XA_WM_SEE_fflNTS 

the  value  of  the  XA_WM_ICON_SIZE 

change  the  standard  colormap 

set  a  window's  WM_CLffiNT_MACHINE 

a  window's  WM_COLORMAP_WINDOWS 

set  a  window  manager  hints 

set  a  window's  XA_WM_ICON_NAME 

set  a  window's  XA_WM_NAME 

a  window's  XA_WM_NORMAL_fflNTS 

set  a  window's  WM_PROTOCOLS 

set  a  window's  WM_SEE_HINTS 

XChangeProperty:  change  a 

/set  the  XA_WM_TRANSIENT_FOR 

/obtain  the  atom  type  and 

/get  a  string  name  for  a 

XGetFontProperty:  get  a  font 

XUstProperries:  get  the 

/return  an  atom  for  a  given 

/gettheXA_WM_CLASS 

/gettheXA_WM  TRANSffiNT_FOR 

/settheXA_WM_CLASS 

state  (not/  /get  the  size  hints 

state  (not/  /set  the  size  hints 

/read  the  size  hints 

/set  the  size  hints 

XGetSizeHints:  read  any 

/set  the  value  of  any 

queue  XPutBackEvent: 

convert  a  string  to  a 

XrmUniqueQuark:  allocate  a  new 

string  to  a  binding  list  and  a 

/convert  a  key  string  to  a 

value  Ao  a  database  using  a 

XrmQuarkToString:  convert  a 

value  using  name  and  class  as 

into  a  database  using 

font  metrics  XQueryTextExtents: 

font/  XQueryTextExtents  16: 

number  of  events  in  the  event 

without  removing  it  from  the 

without  removing  it  from  the 

push  an  event  back  on  the  input 

XChecklfEvent:  check  the  event 

/return  the  next  event  in 

don't/  /return  the  next  event  in 

the  request  buffer  (display  all 

stacking  order  XRaiseWindow: 

XDisplayKeycodes:  obtain  the 

XReadBitmapFile: 

property  XGetWMIconName: 

property  XGetWMName: 

XGetWMNormalHints: 

property  XGetWMSizeHints: 

XA_SIZE_HINTS  XGetSizeHints: 


property  XGetWMHints: 

property  XGetWMIconName: 
property  XGetWMName:  ....... 

property  /read 

property  XGetWMSizeHints: 

property  XSetlcon Sizes:  set ........... 

property  XSetStandardColormap: . 
property  XSetWMClientMachine: 
property  /set 


.XGetWMHints 

.XGetWMIconName 

.XGetWMName 

.XGetWMNormalHints 
..  XGetWMSizeHints 
..  XSetlconSizes 
..  XSetStandardColormap 
...  XSetWMClientMachine 
...  XSetWMColormapWindows 
,.  XSetWMHints 
..XSetWMIconName 
,..  XSetWMName 
..  XSetWMNormalHints 
,.  XSetWMProtocols 


property  XSetWMHints: 

property  XSetWMIconName:  

property.  XSetWMName: 

property  XSetWMNormalHints:  set 

property  XSetWMProtocols: 

property  XSetWMSizeHints: XSetWMSizeHints 

property  associated  with  a/ XChangeProperty 

property  for  a  window  XSetTransientForHint 

property  format  for  a  window  XGetWindowProperty 

property  given  its  atom XGetAtomName 

property  given  its  atom XGelFontProperty 

property  list  for  a  window  XListProperties 

property  name  string XIntemAtom 

property  of  a  window XGetClassHint 

property  of  a  window XGetTransientForHint 

property  of  a  window XSetClassHint 

property  of  a  window  in  normal XGetNormalHints 

property  of  a  window  in  normal XSetNormalHints 

property  of  a  zoomed  window  XGetZoomHints 

property  of  a  zoomed  window  XSetZoomHints 

property  of  type  XA_SIZE_HINTS XGetSizeHints 

property  of  type  XA_SEE_HINTS XSetSizeHints 

push  an  event  back  on  the  input XPutBackEvent 

quark  XrmStringToQuark: XrmStringToQuark 

Quark XrmUniqueQuark 

quark  list  /convert  a  key XrmStringToBindingQuarkList 

quark  list  XrmStringToQuarkList 


....  XrmQPutStringResource 
....  XrmQuarkToString 
....  XrmQGetResource 
....  XrmQPutResource 
....  XQueryTextExtents 
....  XQueryTextExtents  16 
....  XEventsQueued 


quark  resource  name  and  string  

quark  to  a  string 

quarks  /get  a  resource 

quarks  /a  resource  specification  

query  the  server  for  string  and  

query  the  server  for  string  and  ........ 

queue  XEventsQueued:  check  the  ... 

queue  XPeekEvent:  get  an  event XPeekEvent 

queue  /by  predicate  procedure XPeeklfEvent 

queue  XPutBackEvent: XPutBackEvent 

queue  for  a  matching  event XChecklfEvent 

queue  matching  type  and  window  XCheckTypedWindowEvent 

queue  that  matches  event  type;  XCheckTypedEvent 

queued  requests)  XFlush:  flush XFlush 

raise  a  window  to  the  top  of  the XRaiseWindow 

range  of  legal  keycodes  for  a/ XDisplayKeycodes 

read  a  bitmap  from  disk XReadBitmapFile 

read  a  window's  XA_WM_ICON_NAME  XGetWMIconName 

read  a  window's  XA_WM_NAME XGetWMName 

read  a  window's/ XGetWMNormalHints 

read  a  window's  XA_WM_SEE_fflNTS  XGetWMSizeHints 
read  any  property  of  type XGetSizeHints 
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server/  XRefreshKeyboardMapping:  read  keycode-keysym  mapping  from  XRefreshKeyboardMapping 

properties  XGetTextProperty:  read  one  of  a  window's  text  XGetTextProperty 

a  zoomed  window  XGetZoomffints:  read  the  size  hints  property  of XGetZoomHints 

property  XGetWMHints:  read  the  window  manager  hints  XGetWMffints 

XAllocNamedColor:  allocate  a  read-only  colorcell  from  color/ XAllocNamedColor 

closest/  XAllocColor:  allocate  a  read-only  coloimap  cell  with XAllocColor 

name  /set  RGB  values  of  a  read/write  colorcell  by  color XStoreNamedColor 

/set  or  change  the  RGB  values  of  read/write  colorcells  to  the/ XStoreColors 

/or  change  the  RGB  values  of  a  read/write  colormap  entry  to  the/ XStoreColor 

XAllocColorPlanes:  allocate  read/write  (nonshareable)  color/ XAllocColorPlanes 

XAllocColorCells:  allocate  read/write  (nonshared)/ XAllocColorCells 

client  XRebindKeysym:  rebind  a  keysym  to  a  string  for XRebindKeysym 

that  a  top-level  window  be  reconfigured  /request XReconfigureWMWindow 

draw  an  arc  fitting  inside  a  rectangle  XDrawArc:  XDrawArc 

draw  an  outline  of  a  rectangle  XDrawRectangle: XDrawRectangle 

XClipBox:  generate  the  smallest  rectangle  enclosing  a  region XClipBox 

XGetlmage:  place  contents  of  a  rectangle  from  drawable  into  an/ XGetlmage 

location/  XGetSublmage:  copy  a  rectangle  in  drawable  to  a XGetSublmage 

XRectlnRegion:  detemune  if  a  rectangle  resides  in  a  region XRectlnRegion 

XUnionRectWithRegion:  add  a  rectangle  to  a  region XUnionRectWithRegion 

draw  the  outlines  of  multiple  rectangles  XDrawRectangles: XDrawRectangles 

a  graphics  context  to  a  list  of  rectangles  /change  clip_mask  in XSetClipRectangles 

XFillRectangle:  fill  a  rectangular  area XFillRectangle 

XClearArea:  clear  a  rectangular  area  in  a  window  XClearArea 

XFillRectangles:  fill  multiple  rectangular  areas  XFillRectangles 

region  XShrinkRegion:  reduce  or  expand  the  size  of  a XShrinkRegion 

smallest  rectangle  enclosing  a  region  XClipBox:  generate  the XClipBox 

create  a  new  empty  region  XCreateRegion:  XCreateRegion 

storage  associated  with  a  region  /deallocate  XDestroyRegion 

change  offset  of  a  region  XOffsetRegion: XOffsetRegion 

determine  if  a  point  is  inside  a  region  XPointlnRegion: XPointlnRegion 

if  a  rectangle  resides  in  a  region  XRectlnRegion:  determine  XRectlnRegion 

context  to  the  specified  region  /of  the  graphics XSetRegion 

reduce  or  expand  the  size  of  a  region  XShrinkRegion: XShrinkRegion 

add  a  rectangle  to  a  region  XUnionRectWithRegion: XUnionRectWithRegion 

XSubtractRegion:  subtract  one  region  from  another XSubtraciRegion 

XPolygonRegion:  generate  a  region  from  points XPolygonRegion 

XFjnptyRegion:  determine  if  a  region  is  empty XEmptyRegion 

compute  the  intersection  of  two  regions  XIntersectRegion:  XIntersectRegion 

compute  the  union  of  two  regions  XUnionRegion:  XUnionRegion 

union  and  intersection  of  two  regions  /difference  between  the XXorRegion 

XEqualRegion:  determine  if  two  regions  have  the  same  size,/ XEqualRegion 

grab  XUngrabButton:  release  a  button  from  a  passive  XUngrabButton 

XFreeCursor:  release  a  cursor XFreeCursor 

grab  XUngrabKey:  release  a  key  from  a  passive XUngrabKey 

active  grab  XUngrabKeyboard:  release  the  keyboard  from  an  XUngrabKeyboard 

active  grab  XUngrabPointer:  release  the  pointer  from  an XUngrabPointer 

XUngrabServer:  release  the  server  from  grab XUngrabServer 

/destroy  a  client  or  its  remaining  resources XKillClient 

control  list  XRemoveHost:  remove  a  host  from  the  access  XRemoveHost 

client's/  XChangeSaveSet:  add  or  remove  a  subwindow  from  the XChangeSaveSet 

client's/  XRemoveFromSaveSet:  remove  a  window  from  the XRemoveFromSaveSet 

access  control/  XRemoveHosts:  remove  multiple  hosts  from  the XRemoveHosts 

both  passed/  XCheckWindowEvent:  remove  the  next  event  matching  XCheckWindowEvent 

matches  mask  XMaskEvent:  remove  the  next  event  that XMaskEvent 

matches  mask;/  XCheckMaskEvent:  remove  the  next  event  that XCheckMaskEvent 

matches  the/  XWindowEvent:  remove  the  next  event  that XWindowEvent 

XPeekEvent:  get  an  event  without  removing  it  from  the  queue XPeekEvent 
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/by  predicate  procedure  without 

border  pixel  value  attribute  and 

window  border  tile  attribute  and 

connection  to  a/  XDisplayName: 

number  of/  XPending:  flush  the 

events  and/  XSync:  flush  the 

queued/  X Flush:  flush  the 

be  iconified  Xlconify Window: 

be/  XReconfigureWMWindow: 

be  withdrawn  XWithdraw Window: 

list  to  allow  or  deny  connection 

buffer  (display  all  queued 

XResetScreenSaver: 

/determine  if  a  rectangle 

search  prepared  list  for  a  given 

extract  an  option  value  from  the 

XrmDestroyDatabase:  destroy  a 

a  resource  specification  to  a 

a  resource  specification  into  a 

line/  XrmParseCommand:  load  a 

XrmPutFileDatabase:  store  a 

strings  XrmGetResource:  get  a 

the/  /obtain  the  GContext 

Xrmlnitialize:  initialize  the 

Ao  a  database  using  a  quark 

/specification  with  separate 

XrmQPutResource:  store  a 

XrmPutResource:  store  a 

XrmQPutStringResource:  add  a 

XrmPutLineResource:  add  a 

XrmPutStringResource:  add  a 

class  as/  XrmQGetResource:  get  a 

a  client  or  its  remaining 

and  pointer  events  when  these 

XrmGetFileDatabase: 

to  X  supported/  XListExtensions: 

parent,  and  root  XQueryTree: 

XrmQGetSearchList: 

font  names  XListFonts: 

/copy  a  colormap  and 

property  name/  XInternAtom: 

XFetchBuffer: 

XFetchBytes: 

loaded  font  XQueryFont: 

XGetKeyboardMapping: 

focus  window  XGetlnputFocus: 

XCheckTypedWindowEvent: 

that  matches/  XCheckTypedEvent: 

/flush  the  request  buffer  and 

XGetSelectionOwner: 

XLookupColor:  get  database 

XQueryColor:  obtain  the 

colorcells  XQueryColors:  obtain 

or/  XParseColor:  look  up 

/and  closest  hardware-supported 

colorcelV  XStoreNamedColor:  set 

XStoreColor:  set  or  change  the 

XStoreColors:  set  or  change  the 


removing  it  from  the  queue , 

repaint  the  border  /a  window , 

repaint  the  border  /change  a , 

report  the  display  name  (when , 

request  buffer  and  return  the  , 

request  buffer  and  wait  for  all 

request  buffer  (display  all 

request  that  a  top-level  window  

request  that  a  top-level  window  ....... 

request  that  a  top-level  window  ....... 

requests  /use  access  control 

requests)  /flush  the  request  

reset  the  screen  saver 

resides  in  a  region  

resource  XrmQGetSearchResource: 

resource  database  XGetDefault: 

resource  database 

resource  database  /add  ..................... 


resource  database  /store  ... 
resource  database  from  command 
resource  database  in  a  file 
resource  from  name  and  class  as  ....... 

(resource  ID)  associated  with 

resource  manager 

resource  name  and  string  value 
resource  name  and  value 
resource  specification  into  a/ 
resource  specification  into  a/ 
resource  specification  to  a/ 
resource  specification  to  a/ 
resource  specification  with/ 
resource  value  using  name  and 
resources  XKillClient:  destroy 
resources  are  grabbed  /keyboard 
retrieve  a  database  from  a  file 
return  a  list  of  all  extensions 

return  a  list  of  children, 

return  a  list  of  database  levels  

return  a  list  of  the  available  

return  a  new  colormap  ID 

return  an  atom  for  a  given  

return  data  from  a  cut  buffer 

return  data  from  cut  buffer  0  

return  information  about  a 

return  symbols  for  keycodes  

return  the  current  keyboard  

return  the  next  event  in  queue/ 

return  the  next  event  in  queue 

return  the  number  of  pending/ 

return  the  owner  of  a  selection 

RGB  values  and  closest/ 

RGB  values  and  flags  for  a/ 

RGB  values  for  an  array  of 

RGB  values  from  ASCII  color  name  . 

RGB  values  from  color  name 

RGB  values  of  a  read/write  

RGB  values  of  a  read/write/ 

RGB  values  of  read/write/ 


.XPeeklfEvent 

,  XSetWindowBorder 

,  XSetWindowBorderPixmap 

,  XDisplayName 

,  XPending 

,  XSync 

,  XFlush 

,  Xlconify  Window 

,  XReconfigureWMWindow 

,  XWithdrawWindow 

,  XEnableAccessControl 

,  XFlush 

,  XResetScreenSaver 

,  XRectlnRegion 

,  XrmQGetSearchResource 

.  XGetDefault 

.  XrmDestroyDatabase 

,  XrmPutLineResource 

,  XrmPutResource 

,  XrmParseCommand 

.  XrmPutFileDatabase 

.  XrmGetResource 

.  XGContextFromGC 

,  Xrmlnitialize 

,  XrmQPutStringResource 

,  XrmPutStringResource 

,  XrmQPutResource 

.  XrmPutResource 

.  XrmQPutStringResource 

.  XrmPutLineResource 

,  XrmPutStringResource 

,  XrmQGetResource 

.  XKillClient 

.  XAllowEvents 

.  XrmGetFileDatabase 

,  XListExtensions 

,  XQueryTree 

,  XrmQGetSearchList 

,  XListFonts 

,  XCopyColormapAndFree 

,  XInternAtom 

,  XFetchBuffer 

,  XFetchBytes 

,  XQueryFont 

.  XGetKeyboardMapping 

.  XGetlnputFocus 

.  XCheckTypedWindowEvent 

.  XCheckTypedEvent 

.  XPending 

.  XGetSelectionOwner 

.  XLookupColor 

.  XQueryColor 

.  XQueryColors 

.  XParseColor 

.  XLookupColor 

.XStoreNamedColor 

.  XStoreColor 

.  XStoreColors 
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XBell: 

a  list  of  children,  parent,  and 

XRotateWindowProperties : 

XRotateBuffers: 

XSetFillRule:  set  the  fill 

fif  two  regions  have  the 

to  a  window  and/  XSaveContext: 

reset  the  screen 

set  the  parameters  of  the  screen 

/turn  the  screen 

/get  the  current  screen 

add  a  window  to  the  client's 

a  subwindow  from  the  client's 

a  window  from  the  client's 

the  depths  available  on  a  given 

pointer  to  another  point  on  the 

XActivateScreenSaver:  activate 

XResetScreenSaver:  reset  the 

set  the  parameters  of  the 

XForceScreenSaver:  turn  the 

XGetScreenSaver:  get  the  current 

.    new  graphics  context  for  a  given 

get  the  current  font 

XSetFontPath:  set  the  font 

resource  XrmQGetSearchResource: 

sent  to  a  window  XSelectlnput: 

use  the  value  of  a 

return  the  owner  of  a 

set  the  owner  of  a 

connection  with  the/  XNoOp: 

XSendEvent: 

select  the  event  types  to  be 

/a  resource  specification  with 

range  of  legal  keycodes  for  a 

XGrabServer:  grab  the 

to  X  supported  by  Xh'b  and  the 

pixmap  formats  for  a  given 

to  exercise  connection  with  the 

connect  a  client  program  to  an  X 

errors  to  be  processed  by  the 

a  client  program  from  an  X 

XQueryTextExtents:  query  the 

XQueryTextExtentsl6:  query  the 

XUngrabServer:  release  the 

/read  keycode-keysym  mapping  from 

Xlib/  XSetAfterFunction: 

handler  XSetErrorHandler: 

a  graphics  context  XSetDashes: 

XPutPixel: 

property  XSetWMHints: 

manager/  XSetWMProperties: 

property  XSetWMClientMachine: 

XSetWMColormapWindows: 

property  XSetWMProtocols: 

property  XSetWMSizeHints: 

property  XSetWMIconName: 

property.  XSetWMName: 

XSetWMNormalHints : 


XBell 

XQueryTree 

, XRotateWindowProperties 


ring  the  bell  (Control  G)  

root  XQueryTree:  return 

rotate  properties  in  the/ 

rotate  the  cut  buffers  XRotateBuffers 

rule  in  a  graphics  context XSetFillRule 

same  size,  offset,  and  shape XEqualRegion 

save  a  data  value  corresponding  XSaveContext 

saver  XResetScreenSaver: XResetScreenSaver 

saver  XSetScreenSaver: XSetScreenSaver 

saver  on  or  off XForceScreenSaver 

saver  parameters XGetScreenSaver 

save-set  XAddToSaveSet:  XAddToSaveSet 

save-set  /add  or  remove  XChangeSaveSet 

save-set  /remove XRemoveFromSaveSet 

screen  XUstDepths:  determine  XListDepths 

screen  XWarpPointer:  move  the XWarpPointer 

screen  blanking  XActivateScreenSaver 

screen  saver XResetScreenSaver 

screen  saver  XSetScreenSaver: XSetScreenSaver 

screen  saver  on  or  off XForceScreenSaver 

screen  saver  parameters XGetScreenSaver 

screen  with  the  depth  of  the/  /a XCreateGC 

search  path  XGetFontPath: XGetFontPath 

search  path XSetFontPath 

search  prepared  list  for  a  given  

select  the  event  types  to  be 

selection  XConvertSelection:  

selection  XGetSelectionOwner:  .... 

selection  XSetSelectionOwner: 

send  a  NoOp  to  exercise 

send  an  event 

sent  to  a  window  XSelectlnput: XSelectlnput 

separate  resource  name  and  value XrmPutStringResource 

server  /obtain  the  XDisplayKeycodes 

server XGrabServer 

server  /a  list  of  all  extensions XListExtensions 

server  /obtain  the  supported XListPixmapFormats 

server  XNoOp:  send  a  NoOp XNoOp 

server  XOpenDisplay: XOpenDisplay 

server  /wait  for  all  events  and XSync 

server  and  display  /disconnect XCloseDisplay 

server  for  string  and  font/ XQueryTextExtents 

server  for  string  and  font/ XQueryTextExtents  16 

server  from  grab XUngrabServer 

server  into  Xlib XRefreshKeyboardMapping 

set  a  function  called  after  all XSetAfterFunction 

set  a  nonfatal  error  event XSetErrorHandler 

set  a  pattern  of  line  dashes  in XSetDashes 

set  a  pixel  value  in  an  image  XPutPixel 

set  a  window  manager  hints  XSetWMHints 

set  a  window's  standard  window  XSetWMProperties 

set  a  window's  WM_CLIENT_MACHINE  XSetWMClientMachine 

set  a  window's/ XSetWMColormapWindows 

set  a  window's  WM.PROTOCOLS XSetWMProtocols 

set  a  window's  WM_SEE_HINTS XSetWMSizeHints 

set  a  window's  XA_WM_ICON_NAME  XSetWMIconName 

set  a  window's  XA_WM_NAME XSetWMName 

set  a  window's/ XSetWMNormalHints 


XrmQGetSearchResource 

XSelectlnput 

XConvertSelection 

XGetSelectionOwner 

XSetSelectionOwner 

XNoOp 

XSendEvent 
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structure  XSetRGBColormaps: 

create  a  window  and 

context  to  the/  XSetRegion: 

graphics  context  XSetClipMask: 

modifiers/  XSetModifierMapping: 

manager  /set  the  minimum 

properties  XSetTextProperty: 

a  read/write/  XStoreColor: 

read/write/  XStoreColors: 

colorcell  by/  XStoreNamedColor: 

context  XSetArcMode: 

attribute/  XSetWindowBackground: 

in  a  graphics/  XSetBackground: 

operation  in  a/  XSetFunction: 

graphics/  XSetClipOrigin: 

window  XSetWindowColormap: 

graphics  context  XSetFont: 

context  XSetFillRule: 

context  XSetFillStyle: 

context  XSetTile: 

XSetFontPath: 

logical  function,/  XSetState: 

in  a  graphics/  XSetForeground: 

XSetGraphicsExposures: 

XSetlnputFocus: 

in  a/  XSetLine  Attributes: 

XSetStandardProperties : 

a  window's  icon  XSetlconName: 

XSetSelectionOwner: 

saver  XSetScreenSaver: 

context  XSetPlaneMask: 

XSetPointerMapping : 

window  in/  XSetNormalHints: 

zoomed  window  XSetZoomHints: 

XStringListToTextProperty: 

context  XSetStipple: 

graphics/  XSetSubwindowMode: 

graphics  context  XSetTSOrigin: 

type/  XSetSizeHints: 

XA_WM_ICON_SIZE/  XSetlconSizes: 

a  window  XSelClassHint: 

(command  line/  XSetCommand: 

property/  XSetTransientForHint: 

XChangeWindow  Attributes : 

have  the  same  size,  offset,  and 

the  fastest  supported  stipple 

the  fastest  supported  fill  tile 

a  mapping  of  modifier  keys 

keycodes  to  be  used  as  modifiers 

map  a  window  on  top  of  its 

change  the  stacking  order  of 

XGetPixel:  obtain  a 

a  drawable/  XCopyPlane:  copy  a 

cursor,  tile,  or  stipple 

XResize Window:  change  a  window's 

XMoveResize Window:  change  the 

/change  the  window  position, 

geometry/  /generate  position  and 


set  an  XStandardColormap 

set  attributes  XCreate Window: 

set  clip_mask  of  the  graphics  

set  clip_mask  pixmap  in  a  

set  keycodes  to  be  used  as 

set  of  properties  for  the  window 

set  one  of  a  window's  text 

set  or  change  the  RGB  values  of 

set  or  change  the  RGB  values  of 

set  RGB  values  of  a  read/write 

set  the  arc  mode  in  a  graphics  , 

set  the  background  pixel  value , 

set  the  background  pixel  value , 

set  the  bitwise  logical , 

set  the  clip  origin  in  a , 

set  the  colormap  attribute  for  a , 

set  the  current  font  in  a  , 

set  the  fill  rule  in  a  graphics , 

set  the  fill  style  in  a  graphics  , 

set  the  fill  tile  in  a  graphics , 

set  the  font  search  path  , 

set  the  foreground,  background,  , 

set  the  foreground  pixel  value 

set  the  graphics_exposures/ 

set  the  keyboard  focus  window , 

set  the  line  drawing  components , 

set  the  minimum  set  of/ 

set  the  name  to  be  displayed  in  

set  the  owner  of  a  selection  

set  the  parameters  of  the  screen  

set  the  plane  mask  in  a  graphics 

set  the  pointer  button  mapping 

set  the  size  hints  property  of  a 

set  the  size  hints  property  of  a 

set  the  specified  list  of/ 

set  the  stipple  in  a  graphics 

set  the  subwindow  mode  in  a  

set  the  tile/stipple  origin  in  a 

set  the  value  of  any  property  of 

set  the  value  of  the  

set  the  XA_WM_CLASS  property  of .. 
set  the  XA_WM_COMMAND  atom  .. 
set  the  XA_WM_TRANSIENT_FOR 

set  window  attributes  

shape  /determine  if  two  regions 

shape  XQueryBestStipple:  obtain  

shape  XQueryBestTile:  obtain 

(Shift,  Control,  etc.)  /obtain  

(Shift,  Control,  etc.)  /set 

siblings  XMapRaised: 

siblings  XRestackWindows: 

single  pixel  value  from  an  image 

single  plane  of  a  drawable  into 

size  /the  "best"  supported 

SJ2£     ...„.„..„.....„..,....,„.„„.„..... , 

size  and  position  of  a  window 

size,  border  width,  or  stacking/ , 

size  from  standard  window , 


.XSetRGBColormaps 

.  XCreateWindow 

,  XSetRegion 

.  XSetClipMask 

.  XSetModifierMapping 

.  XSetStandardProperties 

.  XSetTextProperty 

.  XStoreColor 

.  XStoreColors 

.  XStoreNamedColor 

.  XSetArcMode 

.  XSetWindowBackground 

.  XSetBackground 

.  XSetFunction 

.  XSetClipOrigin 

.  XSetWindowColormap 

.  XSetFont 

.  XSetFillRule 

.  XSetFillStyle 

.  XSetTile 

.  XSetFontPath 

.XSetState 

.  XSetForeground 

.  XSetGraphicsExposures 

.  XSetlnputFocus 

.  XSetLineAttributes 

.  XSetStandardProperties 

.  XSetlconName 

.  XSetSelectionOwner 

.  XSetScreenSaver 

.  XSetPlaneMask 

.  XSetPointerMapping 

.  XSetNormalHints 

.  XSetZoomHints 

.  XStringListToTextProperty 

.  XSetStipple 

.  XSetSubwindowMode 

.  XSetTSOrigin 

.  XSetSizeHints 

.  XSetlconSizes 

.  XSetClassHint 

.  XSetCommand 

.  XSetTransientForHint 

.  XChangeWindow  Attributes 

.  XEqualRegion 

.  XQueryBestStipple 

.  XQueryBestTile 

.  XGetModifierMapping 

.  XSetModifierMapping 

.XMapRaised 

.  XRestackWindows 

.XGetPixel 

.XCopyPlane 

.  XQueryBestSize 

.  XResizeWindow 

.  XMoveResize  Window 

.  XConfigure  Window 

.  XParseGeometry 
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in/  XGetNormalHints:  get  the   size  hints  property  of  a  window  XGetNormalHints 

in/  XSetNormalHints:  set  the   size  hints  property  of  a  window XSetNormalHints 

window  XGetZoomHints:  read  the   size  hints  property  of  a  zoomed  XGetZoomHints 

window  XSetZoomHints:  set  the   size  hints  property  of  a  zoomed  XSetZoomHints 

reduce  or  expand  the   size  of  a  region  XShrinkRegion:  XShrinkRegion 

/if  two  regions  have  the  same    size,  offset,  and  shape XEqualRegion 

get  preferred  icon   sizes  XGetlconSizes: XGetlconSizes 

get  the  closest  supported  cursor   sizes  XQueryBestCurson XQueryBestCursor 

region  XClipBox:  generate  the   smallest  rectangle  enclosing  a XClipBox 

using  quarks  /store  a  resource   specification  into  a  database XrmQPutResource 

XrmPutResource:  store  a  resource   specification  into  a  resource/ XrmPutResource 

using  a  quark/  /add  a  resource    specification  to  a  database XrmQPutStringResource 

database  /add  a  resource    specification  to  a  resource XrmPutLJneResource 

resource  name/  /add  a  resource    specification  with  separate  XrmPutStringResource 

the  RGB  values  and  flags  for  a   specified  colorcell  /obtain XQueryColor 

screen  with  the  depth  of  the   specified  drawable  /for  a  given XCreateGC 

/ID)  associated  with  the    specified  graphics  context XGContextFromGC 

XTextProperty  structure  /set  the   specified  list  of  strings  to  an XStringlastToTextProperty 

/the  next  event  that  matches  the    specified  mask  and  window  XWindowEvent 

Xh'b  function  XFree:  free   specified  memory  allocated  by  an  XFree 

/structure  associated  with  the    specified  property XGetRGBColormaps 

of  the  graphics  context  to  the    specified  region  /set  clip_mask  XSetRegion 

data  associated  with  the    specified  string  list  /in-memory XFreeStringList 

structures  that  match  the   specified  template  /information XGetVisuallnfo 

/obtain  a  list  of  strings  from  a    specified  XTextProperty/ XTextProperty ToStringList 

bottom  child  to  the  top  of  the    stacking  order  /circulate  the XCirculateSubwindowsDown 

top  child  to  the  bottom  of  the    stacking  order  /circulate  the XCirculateSubwindowsUp 

position,  size,  border  width,  or   stacking  order  /the  window XConfigure Window 

lower  a  window  in  the    stacking  order  XLowerWindow: XLowerWindow 

raise  a  window  to  the  top  of  the    stacking  order  XRaiseWindow: XRaiseWindow 

down  /circulate  the    stacking  order  of  children  up  or XCirculateSubwindows 

XRestack Windows:  change  the    stacking  order  of  siblings XRestack Windows 

XGetStandardColormap:  get  the    standard  colormap  property XGetStandardColormap 

XSetStandardColormap:  change  the    standard  colormap  property XSetStandardColormap 

/create  a  cursor  from  the    standard  cursor  font  XCreateFontCursor 

/generate  position  and  size  from    standard  window  geometry  string XParseGeometry 

XSetWMProperties:  set  a  window's    standard  window  manager/ XSetWMProperties 

/property  of  a  window  in  normal   state  (not  zoomed  or  iconified)  XGetNormalHints 

/property  of  a  window  in  normal   state  (not  zoomed  or  iconified)  XSetNormalHints 

a  bit  vector  for  the  current   state  of  the  keyboard  /obtain XQueryKeymap 

XSetStipple:  set  the    stipple  in  a  graphics  context XSetStipple 

/obtain  the  fastest  supported    stipple  shape  XQueryBestStipple 

supported  cursor,  tile,  or   stipple  size  /the  "best"  XQueryBestSize 

XDestroyRegion:  deallocate    storage  associated  with  a  region XDestroyRegion 

/unload  a  font  and  free   storage  for  the  font  structure  XFreeFont 

file  XrmPutFileDatabase:    store  a  resource  database  in  a XrmPutFileDatabase 

into  a/  XrmQPutResource:    store  a  resource  specification  XrmQPutResource 

into  a  resource/  XrmPutResource:   store  a  resource  specification  XrmPutResource 

XStoreBuffer:    store  data  in  a  cut  buffer XStoreBuffer 

XStoreBytes:    store  data  in  cut  buffer  0 XStoreBytes 

atom  for  a  given  property  name   string  XIntemAtom:  return  an XIntemAtom 

convert  a  keysym  symbol  to  a   string  XKeysymToString: XKeysymToString 

from  standard  window  geometry    string  /position  and  size XParseGeometry 

metrics  of  a  16-bit  character   string  /for  string  and  font  XQueryTextExtents  16 

create  a  database  from  a    string  XrmGetStringDatabase:  XrmGetStringDatabase 

convert  a  quark  to  a    string  XrmQuarkToString: XrmQuarkToString 

/geometry  given  user  geometry    string  and  default  geometry XGeometry 

/query  the  server  for   string  and  font  metrics  XQueryTextExtents 
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XTextExtents:  get  string  and  font  metrics  locally XTextExtents 

16-bit/  /query  the  server  for  string  and  font  metrics  of  a XQueryTextExtentsl6 

1 6-bit/  XTextExtents  1 6:  get  string  and  font  metrics  of  a XTextExtents  1 6 

/rebind  a  keysym  to  a  string  for  client XRebindKeysym 

XDrawString:  draw  an  8-bit  text  string,  foreground  only XDrawString 

Anap  a  key  event  to  ASCII  string,  keysym,  and/ XLookupString 

associated  with  the  specified  string  list  /the  in-memory  data XFreeStringList 

metrics  of  a  16-bit  character  string,  locally  /string  and  font XTextExtents  16 

in  pixels  of  an  8-bit  character  string,  locally  /get  the  width XTextWidth 

in  pixels  of  a  16-bit  character  string,  locally  /get  the  width XTextWidth  16 

its  atom  XGetAtomName:  get  a  string  name  for  a  property  given XGetAtomName 

quark  list  /convert  a  key  string  to  a  binding  list  and  a  XrmStringToBindingQuarkList 

/convert  a  keysym  name  string  to  a  keysym  XStringToKeysym 

XrmStringToQuark:  convert  a  string  to  a  quark XrmStringToQuark 

/convert  a  key  string  to  a  quark  list XrmStringToQuarkList 

using  a  quark  resource  name  and  string  value  Ao  a  database XrmQPutStringResource 

draw  two-byte  text  strings  XDrawString  16:  XDrawString  16 

XDrawText:  draw  8-bit  polytext  strings XDrawText 

draw  16-bit polytext  strings  XDrawTextl6:  XDrawTextl6 

resource  from  name  and  class  as  strings  XrmGetResource:  get  a XrmGelResource 

XTextProperty/  /obtain  a  list  of  strings  from  a  specified XTextPropertyToSlringList 

/set  the  specified  list  of  strings  to  an  XTextProperty/ XStringListToTextProperty 

allocate  an  XClassHint  structure  XAllocClassHint: XAllocClassHint 

allocate  an  XlconSize  structure  XAllocIconSize: XAllocIconSize 

allocate  an  XSizeHints  structure  XAllocSizeHints: XAllocSizeHints 

/allocate  an  XStandardColormap  structure  XAllocStandardColormap 

allocate  an  XWMHints  structure  XAllocWMHints: XAllocWMHints 

allocate  memory  for  an  Xlmage  structure  XCreatelmage:  XCreatelmage 

an  entry  from  an  XModifierKeymap  structure  /delete XDeleteModifiermapEntry 

and  free  storage  for  the  font  structure  Ainload  a  font  XFreeFont 

free  a  keyboard  modifier  mapping  structure  /destroy  and XFreeModifiermap 

new  entry  to  an  XModifierKeymap  structure  /add  a XlnsertModifiermapEntry 

load  a  font  and  fill  information  structure  XLoadQueryFont: XLoadQueryFont 

corresponding  to  a  keycode  in  structure  /get  the  keysym  XLookupKeysym 

a  keyboard  modifier  mapping  structure  /create XNewModifiermap 

set  an  XStandardColormap  structure  XSetRGBColormaps:  XSetRGBColormaps 

of  strings  to  an  XTextProperty  structure  /the  specified  list  XStringListToTextProperty 

from  a  specified  XTextProperty  structure  /a  list  of  strings XTextProperty ToStringList 

/obtain  the  XStandardColormap  structure  associated  with  the/ XGetRGBColormaps 

A"ind  the  visual  information  structures  that  match  the/ XGetVisuallnfo 

XSetFillStyle:  set  the  fill  style  in  a  graphics  context XSetFillStyle 

XSublmage:  create  a  subimage  from  part  of  an  image  XSublmage 

XSubtractRegion:  subtract  one  region  from  another XSubtractRegion 

XChangeSaveSet:  add  or  remove  a  subwindow  from  the  client's/ XChangeSaveSet 

XSetSubwindowMode:  set  the  subwindow  mode  in  a  graphics/ XSetSubwindowMode 

and  destroy  a  window  and  all  subwindows.  Ainmap XDestroy Window 

XUnmapSubwindows:  unmap  all  subwindows  of  a  given  window XUnmapSubwindows 

XDestroySubwindows:  destroy  all  subwindows  of  a  window XDestroySubwindows 

XMapSubwindows:  map  all  subwindows  of  window XMapSubwindows 

/change  the  keyboard  preferences  such  as  key  click  XChangeKeyboardControl 

/a  list  of  all  extensions  to  X  supported  by  Xlib  and  the  server XListExtensions 

/get  the  closest  supported  cursor  sizes XQueryBestCursor 

stipple/  /obtain  the  "best"  supported  cursor,  tile,  or XQueryBestSize 

/obtain  the  fastest  supported  fill  tile  shape XQueryBestTile 

XlistPixmapFormats:  obtain  the  supported  pixmap  formats  for  a/ XlistPixmapFormats 

/obtain  the  fastest  supported  stipple  shape XQueryBestStipple 

/convert  a  keysym  symbol  to  a  string XKeysymToString 

XGetKeyboardMapping:  return  symbols  for  keycodes  XGetKeyboardMapping 
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XSynchronize:  enable  or  disable  synchronization  for  debugging  XSynchronize 

another  /change  the  coordinate  system  from  one  window  to XTranslateCoordinates 

an  entry  from  an  association  table.  XDeleteAssoc:  delete XDeleteAssoc 

allocated  for  an  association  table,  /free  the  memory  XDestroyAssocTable 

obtain  data  from  an  association  table  XLookUpAssoc: XLookUpAssoc 

an  entry  in  an  association  table  XMakeAssoc:  create XMakeAssoc 

create  a  new  association  table  (X10)  XCreateAssocTable: XCreateAssocTable 

that  match  the  specified  template  /information  structures XGetVisuallnfo 

/draw  8-bit  image  text  characters XDrawImageString 

/draw  16-bit  image  text  characters XDrawImageString  16 

/read  one  of  a  window's  text  properties XGetTextProperty 

/set  one  of  a  window's  text  properties XSetTextProperty 

XDrawString:  draw  an  8-bit  text  string,  foreground  only XDrawString 

XDrawString  16:  draw  two-byte  text  strings XDrawString  1 6 

border  /change  a  window  border  tile  attribute  and  repaint  the XSetWindowBorderPixmap 

/change  the  background  tile  attribute  of  a  window XSetWindowBackgroundPixmap 

XSelTile:  set  the  fill  tile  in  a  graphics  context XSetTile 

the  "best"  supported  cursor,  tile,  or  stipple  size  /obtain  XQueryBestSize 

the  fastest  supported  fill  tile  shape  /obtain XQueryBestTile 

graphics/  XSetTSOrigin:  set  the  tile/stipple  origin  in  a  XSetTSOrigin 

stacking  order  /circulate  the  top  child  to  the  bottom  of  the  XCirculateSubwindowsUp 

XMapRaised:  map  a  window  on  top  of  its  siblings  XMapRaised 

/the  bottom  child  to  the  top  of  the  stacking  order XCirculateSubwindowsDown 

/raise  a  window  to  the  top  of  the  stacking  order XRaiseWindow 

Xlconify Window:  request  that  a  top-level  window  be  iconified XlconifyWindow 

/request  that  a  top-level  window  be  reconfigured  XReconfigureWMWindow 

XWithdrawWindow:  request  that  a  top-level  window  be  withdrawn XWithdrawWindow 

values  from  ASCII  color  name  or  translate  hexadecimal  value  /RGB  XParseColor 

auto-repeat/  XAutoRepeatOff :  turn  off  the  keyboard  XAutoRepeatOff 

keys  XAutoRepeatOn:  turn  on  the  keyboard  auto-repeat XAutoRepeatOn 

XForceScreenSaver:  turn  the  screen  saver  on  or  off XForceScreenSaver 

/create  a  cursor  from  two  bitmaps  XCreatePixmapCursor 

XDrawLine:  draw  a  line  between  two  points  XDrawLine 

compute  the  intersection  of  two  regions  XInterseclRegion:  XIntersectRegion 

compute  the  union  of  two  regions  XUnionRegion: XUnionRegion 

the  union  and  intersection  of  two  regions  /difference  between XXorRegion 

XEqualRcgion:  determine  if  two  regions  have  the  same  size/ XEqualRegion 

XDrawStringl6:  draw  two-byte  text  strings XDrawStringl6 

entry  for  a  given  window  and  type  /delete  a  context XDeleteContext 

window  /obtain  the  atom  type  and  property  format  for  a  XGetWindowProperty 

the  next  event  in  queue  matching  type  and  window  /return  XCheckTypedWindowEvent 

in  queue  that  matches  event  type;  don't  wait  /the  next  event XCheckTypedEvent 

Ao  a  window  and  context  type  (not  graphics  context) XSaveContext 

get  the  next  event  of  any  type  or  window  XNextEvent: XNextEvent 

/read  any  property  of  type  XA_SEE_fflNTS  XGetSizeHints 

/set  the  value  of  any  property  of  type  XA_SEE_HINTS  XSetSizeHints 

XSelectlnput:  select  the  event  types  to  be  sent  to  a  window  XSelectlnput 

default  if/  XUninstallColormap:  uninstall  a  colormap;  install XUninstallColormap 

/the  difference  between  the  union  and  intersection  of  two/ XXorRegion 

XUnionRegion:  compute  the  union  of  two  regions  XUnionRegion 

XUnloadFont:  unload  a  font XUnloadFont 

for  the  font/  XFreeFont:  unload  a  font  and  free  storage XFreeFont 

XUnmapWindow:  unmap  a  window XUnmapWindow 

window  XUnmapSubwindows:  unmap  all  subwindows  of  a  given XUnmapSubwindows 

all  subwindows.  XDestroyWindow:  unmap  and  destroy  a  window  and  XDestroyWindow 

XCreateSimple Window:  create  an  unmapped  InputOutput  window  XCreateSimple Window 

/calculate  window  geometry  given  user  geometry  string  and  default/ XGeometry 

/specification  to  a  database  using  a  quark  resource  name  and/ XrmQPutStringResource 
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/get  a  resource  value  using  name  and  class  as  quarks XrmQGetResource 

specification  into  a  database  using  quarks  /store  a  resource XrmQPutResource 

name  or  translate  hexadecimal  value  /values  from  ASCII  color XParseColor 

with  separate  resource  name  and  value  /a  resource  specification XrmPutStringResource 

a  quark  resource  name  and  string  value  /to  a  database  using  XrmQPutSlringResource 

/change  a  window  border  pixel  value  attribute  and  repaint  the/ XSetWindowBorder 

/set  the  background  pixel  value  attribute  of  a  window XSetWindowBackground 

and/  XSaveContext:  save  a  data  value  corresponding  to  a  window XSaveContext 

XGetPixel:  obtain  a  single  pixel  value  from  an  image  XGetPixel 

XGetDefault:  extract  an  option  value  from  the  resource  database XGetDefault 

/set  the  background  pixel  value  in  a  graphics  context XSetBackground 

/set  the  foreground  pixel  value  in  a  graphics  context XSetForeground 

a  constant  value  to  every  pixel  value  in  an  image  /add  XAddPixel 

XPutPixel:  set  a  pixel  value  in  an  image  XPutPixel 

XConvertSelection:  use  the  value  of  a  selection XConvertSelection 

XSetSizeHints:  set  the  value  of  any  property  of  type/ XSetSizeHints 

property  XSetlconSizes:  set  the  value  of  the  XA_WM_ICON_SIZE XSetlconSizes 

image  XAddPixel:  add  a  constant  value  to  every  pixel  value  in  an  XAddPixel 

XrmQGetResource:  get  a  resource  value  using  name  and  class  as/ XrmQGetResource 

with  depth,  applying  pixel  values  /drawable  into  a  drawable  XCopyPlane 

XLookupColor:  get  database  RGB  values  and  closest/ XLookupColor 

XQueryColor:  obtain  the  RGB  values  and  nags  for  a  specified/ XQueryColor 

XQueryColors:  obtain  RGB  values  for  an  array  of/ XQueryColors 

XParseColor:  look  up  RGB  values  from  ASCII  color  name  or/ XParseColor 

closest  hardware-supported  RGB  values  from  color  name  /and  XLookupColor 

by/  XStoreNamedColor:  set  RGB  values  of  a  read/write  colorcell  XStoreNamedColor 

entry  to/  /set  or  change  the  RGB  values  of  a  read/write  colormap XStoreColor 

to  the/  /set  or  change  the  RGB  values  of  read/write  colorcells XStoreColors 

the/  XQueryKeymap:  obtain  a  bit  vector  for  the  current  state  of  XQueryKeymap 

draw  a  polyline  or  curve  between  vertex  list  (from  X10)  XDraw:  XDraw 

a  filled  polygon  or  curve  from  vertex  list  (from  X10)  /draw  XDrawFilled 

obtain  the  visual  ID  from  a  Visual  XVisuallDFrom Visual: XVisuallDFrom Visual 

XVisuallDFrom  Visual:  obtain  the  visual  ID  from  a  Visual XVisuallDFrom  Visual 

that/  XGetVisuallnfo:  find  the  visual  information  structures XGetVisuallnfo 

XMatchVisuallnfo:  obtain  the  visual  information  that  matches/ XMatchVisuallnfo 

event  that  matches  mask;  don't  wait  /remove  the  next XCheckMaskEvent 

that  matches  event  type;  don't  wait  /the  next  event  in  queue XCheckTypedEvent 

window  and  passed  mask;  don't  wait  /event  matching  both  passed XCheckWindowEvent 

to/  /flush  the  request  buffer  and  wait  for  all  events  and  errors  XSync 

predicate  procedure  XlfEvent:  wait  for  event  matched  in  XlfEvent 

fails)  /report  the  display  name  (when  connection  to  a  display XDisplayName 

character/  XTextWidthl6:  get  the  width  in  pixels  of  a  16-bit XTextWidthl6 

character/  XTextWidth:  get  the  width  in  pixels  of  an  8-bit XTextWidth 

/change  the  border  width  of  a  window XSetWindowBorderWidth 

window  position,  size,  border  width,  or  stacking  order  /the  XConfigure Window 

a  property  associated  with  a  window  XChangeProperty:  change  XChangeProperty 

event  in  queue  matching  type  and  window  /return  the  next  XCheckTypedWindowEvent 

clear  a  rectangular  area  in  a  window  XClearArea: XClearArea 

XClearWindow:  clear  an  entire  window  XClearWindow 

create  an  unmapped  InputOutput  window  XCreateSimple Window: XCreateSimpleWindow 

assign  a  cursor  to  a  window  XDefineCursor: XDefineCursor 

destroy  all  subwindows  of  a  window  XDestroySubwindows: XDestroySubwindows 

the  XA_WM_CLASS  property  of  a  window  XGetClassHint:  get XGetClassHint 

the  current  keyboard  focus  window  XGetlnputFocus:  return , XGetlnputFocus 

property  of  a  window  /the  XA_WM_TRANSIENT_FOR  XGetTransientForHint 

obtain  the  current  attributes  of  window  XGetWindow Attributes: XGetWindow Attributes 

type  and  property  format  for  a  window  /obtain  the  atom XGetWindowProperty 

size  hints  property  of  a  zoomed  window  XGetZoomHints:  read  the  XGetZoomHints 
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get  the  property  list  for  a  window  XListProperties:  XListProperties 

map  all  subwindows  of  window  XMapSub windows:  XMapSubwindows 

XMapWindow:  map  a  window  XMap Window 

the  size  and  position  of  a  window  /change XMoveResize Window 

XMove Window:  move  a  window  XMoveWindow 

the  next  event  of  any  type  or  window  XNextEvent:  get XNextEvent 

the  event  types  to  be  sent  to  a  window  XSelectlnput:  select XSelectlnput 

the  XA_WM_CLASS  property  of  a  window  XSetClassHint:  set XSetClassHint 

set  the  keyboard  focus  window  XSetlnputFocus:  XSetlnputFocus 

property  for  a  window  /the  XA_WM_TRANSIENT_FOR  XSetTransientForHint 

pixel  value  attribute  of  a  window  /set  the  background XSetWindowBackground 

background  tile  attribute  of  a  window  /change  the XSetWindowBackgroundPixmap 

change  the  border  width  of  a  window  XSetWindowBorderWidth: XSetWindowBorderWidth 

set  the  colormap  attribute  for  a  window  XSetWindowColormap:  XSetWindowColormap 

size  hints  property  of  a  zoomed  window  XSetZoomHints:  set  the XSetZoomHints 

disassociate  a  cursor  from  a  window  XUndefineCursor: XUndefineCursor 

unmap  all  subwindows  of  a  given  window  XUnmapSubwindows: XUnmapSubwindows 

XUnmapWindow:  unmap  a  window  XUnmapWindow 

matches  the  specified  mask  and  window  /the  next  event  that XWindowEvent 

/unmap  and  destroy  a  window  and  all  subwindows XDestroy Window 

/a  data  value  corresponding  to  a  window  and  context  type  (not/ XSaveContext 

/insert  a  window  between  another  window  and  its  parent XReparentWindow 

/next  event  matching  both  passed  window  and  passed  mask;  don't/ XCheckWindowEvent 

XCreate Window:  create  a  window  and  set  attributes  XCreate Window 

a  context  entry  for  a  given  window  and  type  /delete  XDeleteContext 

XChangeWindow Attributes:  set  window  attributes XChangeWindow Attributes 

/request  that  a  top-level  window  be  iconified Xlconify  Window 

/request  that  a  top-level  window  be  reconfigured XReconfigureWMWindow 

/request  that  a  top-level  window  be  withdrawn XWithdrawWindow 

and/  XReparentWindow:  insert  a  window  between  another  window  XReparentWindow 

XSetWindowBorder:  change  a  window  border  pixel  value/ XSetWindowBorder 

XSetWindowBorderPixmap:  change  a  window  border  tile  attribute  and/ XSetWindowBorderPixmap 

XStoreName:  assign  a  name  to  a  window  for  the  window  manager  XStoreName 

XRemoveFromSaveSet:  remove  a  window  from  the  client's/ XRemoveFromSaveSet 

geometry/  XGeometry:  calculate  window  geometry  given  user XGeometry 

position  and  size  from  standard  window  geometry  string  /generate XParseGeometry 

/get  the  size  hints  property  of  a  window  in  normal  state  (not/ XGetNormalHints 

/set  the  size  hints  property  of  a  window  in  normal  state  (not/ XSetNormalHints 

XLowerWindow:  lower  a  window  in  the  stacking  order XLowerWindow 

set  of  properties  for  the  window  manager  /set  the  minimum  XSetStandardProperties 

a  name  to  a  window  for  the  window  manager  /assign XStoreName 

XGetWMHints:  read  the  window  manager  hints  property XGetWMHints 

XSetWMHints:  set  a  window  manager  hints  property XSetWMHints 

/set  a  window's  standard  window  manager  properties  XSetWMProperties 

XMapRaised:  map  a  window  on  top  of  its  siblings  XMapRaised 

XPutlmage:  draw  an  image  on  a  window  or  pixmap  XPutlmage 

XConfigureWindow:  change  the  window  position,  size,  border/ XConfigureWindow 

XDeleteProperty:  delete  a  window  property  XDeleteProperty 

the  coordinate  system  from  one  window  to  another  /change XTranslateCoordinates 

XAddToSaveSet:  add  a  window  to  the  client's  save-set XAddToSaveSet 

stacking/  XRaise Window:  raise  a  window  to  the  top  of  the XRaiseWindow 

XWMGeometry:  obtain  a  window's  geometry  information XWMGeometry 

the  name  to  be  displayed  in  a  window's  icon  XSetlconName:  set XSetlconName 

property)  XFetchName:  get  a  window's  name  (XA_WM_NAME XFetchName 

XResize Window:  change  a  window's  size XResizeWindow 

XSetWMProperties:  set  a  window's  standard  window  manager/  . —  XSetWMProperties 

XGetTextProperty:  read  one  of  a  window's  text  properties  XGetTextProperty 

XSetTextProperty:  set  one  of  a  window's  text  properties  XSetTextProperty 
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XSetWMCIientMachine:  set  a 

XSetWMColoimap Windows:  set  a 

XSetWMProtocols:  set  a 

XSetWMSizeHints:  set  a 

property  XGetWMIconName:  read  a 

property  XSetWMIconName:  set  a 

XGetWMName:  read  a 

XSetWMName:seta 

XGetWMNormalHints:  read  a 

XSetWMNormalHints:  set  a 

XGetWMSizeHints:  read  a 

that  a  top-level  window  be 

/set  a  window's 

/set  a  window's 

XSetWMProtocols:  set  a  window's 

XSetWMSizeHints:  set  a  window's 

XWriteBitmapFile: 

connect  a  client  program  to  an 

a  client  program  from  an 

/a  list  of  all  extensions  to 

create  a  new  association  table 

curve  between  vertex  list  (from 

or  curve  from  vertex  list  (from 

/create  a  bitmap  from 

read  any  property  of  type 

value  of  any  property  of  type 

XGetClassHint:  get  the 

XSetClassHint:  set  the 

arguments)  XSetCommand:  set  the 

XGetWMIconName:  read  a  window's 

XSetWMIconName:  set  a  window's 

/set  the  value  of  the 

XFetchName:  get  a  window's  name 

XGetWMName:  read  a  window's 

XSetWMName:  set  a  window's 

/read  a  window's 

/set  a  window's 

XGetWMSizeHints:  read  a  window's 

a/  XSetTransientForHint:  set  the 

a/  XGetTransientForHint:  get  the 

XAllocClassHint:  allocate  an 

free  the  memory  allocated  by 

XAllocIconSize:  allocate  an 

allocate  memory  for  an 

components  of  a  given  GC  from 

free  the  memory  allocated  by 

/free  the  memory  allocated  by 

/delete  an  entry  from  an 

/add  a  new  entry  to  an 

XAllocSizeHints:  allocate  an 

/allocate  an 

XSetRGBColormaps:  set  an 

XGetRGBColormaps:  obtain  the 

specified  list  of  strings  to  an 

list  of  strings  from  a  specified 

XAllocWMHints:  allocate  an 

of  a  window  in  normal  state  (not 

of  a  window  in  normal  state  (not 


window's  WM_CLIENT_MACHINE/  ...  XSetWMCIientMachine 
window's  WM_COLORMAP_WINDOWS/  XSetWMColormapWindows 
window's  WM_PROTOCOLS  property  .  XSetWMProtocols 
window's  WM_SIZE_HINTS  property  ..  XSetWMSizeHints 

window's  XA_WMJCON_NAME XGetWMIconName 

window's  XA_WM_ICON_NAME XSetWMIconName 

window's  XA_WM_NAME  property XGetWMName 

window's  XA_WM_NAME  property XSetWMName 

window's  XA_WM_NORMAL_HINTS/  XGetWMNormalHints 
window's  XA_WM_NORMAL_HINTS/  XSetWMNormalHints 

window's  XA_WM_SEE_fflNTS/ XGetWMSizeHints 

withdrawn  /request XWithdrawWindow 

WM_CLIENT_MACHINE  property XSetWMCIientMachine 

WM_COLORMAP_WINDOWS  property  XSetWMColormapWindows 

WM_PROTOCOLS  property XSetWMProtocols 

WM_SEE_fflNTS  property XSetWMSizeHints 

write  a  bitmap  to  a  file  XWriteBitmapFile 

X  server  XOpenDisplay: XOpenDisplay 

X  server  and  display  /disconnect XCloseDisplay 

X  supported  by  Xlib  and  the/ XListExtensions 

(X10)  XCreateAssocTable: XCreateAssocTable 

X10)  XDraw:  draw  a  polyline  or XDraw 

X10)  /draw  a  filled  polygon XDrawFilled 

XI 1  bitmap  format  data XCreateBitmapFromData 

XA_SEE_fflNTS  XGetSizeHints: XGetSizeHints 

XA_SEE_HINTS  /set  the XSetSizeHints 

XA_WM_CLASS  property  of  a  window  .XGetClassHint 
XA_WM_CLASS  property  of  a  window .  XSetClassHint 
XA_WM_COMMAND  atom  (command  line  XSetCommand 

XA_WM_ICON_NAME  property  XGetWMIconName 

XA_WM_ICON_NAME  property  XSetWMIconName 

XA_WM_ICON_SIZE  property XSetlconSizes 

(XA_WM_NAME  property) XFetchName 

XA_WM_NAME  property XGetWMName 

XA_WM_NAME  property XSetWMName 

XA_WM_NORMAL_fflNTS  property  ..  XGetWMNormalHints 
XA_WM_NORMAL_HINTS  property  ..  XSetWMNormalHints 

XA_WM_SEE_HINTS  property XGetWMSizeHints 

XA_WM_TRANSIENT_FOR  property  for  XSetTransientForHint 
XA_WM_TRANSIENT_FOR  property  of  XGetTransientForHint 


XClassHint  structure 

XGetFontPath  XFreeFontPath:  ... 

XlconSize  structure 

Xlmage  structure  XCreatelmage: 

Xlib's  GC  cache  /obtain 

XListFonts.  XFreeFontNames:  .... 

XListFontsWithlnfo 

XModifierKeymap  structure  

XModifierKeymap  structure  

XSizeHints  structure 

XStandardColormap  structure 

XStandardColormap  structure 

XStandardColormap  structure/ 

XTextProperty  structure  /set  the 

XTextProperty  structure  /a 

XWMHints  structure 

zoomed  or  iconified)  /property 

zoomed  or  iconified)  /property 


XAllocClassHint 

XFreeFontPath 

XAllocIconSize 

XCreatelmage 

XGetGCValues 

XFreeFontNames 

XFreeFontlnfo 

XDeleteModifiermapEntry 

XlnsertModifiermapEntry 

XAllocSizeHints 

XAllocStandardColormap 

XSetRGBColormaps 

XGetRGBColormaps 

XStringListToTextProperty 

XTextPropertyToStringList 

XAllocWMHints 

XGetNormalHints 

XSetNormalHints 
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the  size  hints  property  of  a   zoomed  window  /read XGetZoomHints 

set  the  size  hints  property  of  a    zoomed  window  XSetZoomHints: XSetZoomHints 
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-xiib-  Function  Group /  Introduction 

This  page  describes  the  format  of  each  reference  page  in  this  volume. 


Name 

XFunctionName  —  brief  description  of  the  function. 

Synopsis 

The  Synopsis  section  presents  the  calling  syntax  for  the  routine,  including  the  declarations  of 
the  arguments  and  return  type.  For  example: 

returntype  XFunctionName ( argl ,  arg2 ,  arg3) ; 
typel  argl ; 

type2  *arg2;  /*  RETURN  */ 

type3  *arg3;  /*  SEND  and  RETURN  */ 

The  return  type  Status  is  of  type  int;  it  returns  either  True  or  False  to  indicate  whether 
the  routine  was  successful. 

Arguments 

The  Arguments  section  describes  each  of  the  arguments  used  by  the  function.  There  are  three 
sorts  of  arguments:  arguments  that  specify  data  to  the  function,  arguments  that  return  data  from 
the  function,  and  arguments  that  do  both.  An  example  of  each  type  is  shown  below: 

argl  Specifies  information  for  XFunctionName.  The  description  of  arguments  that 

pass  data  to  the  function  always  begins  with  the  word  "Specifies,"  as  shown  in  this 
example. 

arg2  Returns  a  pointer  to  data  to  be  filled  in  by  XFunctionName.  The  description  of 

arguments  that  return  data  from  the  function  always  begins  with  the  word 
"Returns." 

arg3  Specifies  information  for  XFunctionName,  and  returns  data  from  the  function. 

The  description  of  arguments  that  both  pass  data  to  the  function  and  return  data 
from  the  function  uses  both  the  words  "Specifies"  and  "Returns." 

Availability 

The  Availability  section  specifies  that  a  given  function  is  only  available  in  Release  4  and  later 
releases.  If  there  is  no  Availability  section,  the  function  is  available  prior  to  Release  4. 

Description 

The  Description  section  describes  what  the  function  does,  what  it  returns,  and  what  events  or 
side-effects  it  causes.  It  also  contains  miscellaneous  information  such  as  examples  of  usage, 
special  error  cases,  and  pointers  to  related  information  in  both  volumes  of  this  manual. 

Structures 

The  Structures  section  contains  the  C  definitions  of  the  X-specific  data  types  used  by 
FunctionName  as  arguments  or  return  values.  It  also  contains  definitions  of  important  con- 
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slants  used  by  the  function.  Additional  structures  not  shown  can  be  found  in  Appendix  F, 
Structure  Reference. 

Errors 

The  general  description  of  the  error  types  is  contained  in  Appendix  B,  Error  Messages  and  Pro 
tocol  Requests.  Some  functions  generate  errors  due  to  function-specific  interpretation  of  argu 
ments.  Where  appropriate,  these  function-specific  causes  have  been  listed  along  with  the  error 
event  types  they  generate. 

Related  Commands 

The  Related  Commands  section  lists  the  Xlib  functions  and  macros  related  to  XFunct ion- 
Name. 
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— Xlib  -  Screen  Saver- 


J  XActivateScreenSaver 


Name 

XActivateScreenSaver  —  activate  screen  blanking. 
Synopsis 

XActivateScreenSaver (display) 
Display  *di splay; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

Description 

XActivateScreenSaver  turns  on  the  screen  saver  using  the  parameters  set  with  XSet- 
ScreenSaver.  The  screen  saver  blanks  the  screen  or  makes  random  changes  to  the  display 
in  order  to  save  the  phosphors  from  burnout  when  the  screen  is  left  unattended  for  an  extended 
period  of  time.  The  interval  that  the  server  will  wait  before  starting  screen  save  activity  can  be 
set  with  XSetScreenSaver.  Exactly  how  the  screen  saver  works  is  server-dependent. 

For  more  information  on  the  screen  saver,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 

Related  Commands 

XForceScreenSaver, XGetScreenSaver, XResetScreenSaver,  XSetScreen 
Saver. 
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XAddHOSt Xnb-Hos.Accsss- 

Name 

XAddHost  —  add  a  host  to  the  access  control  list. 

Synopsis 

XAddHost  (display,  host) 
Display  *display; 
XHostAddress  *host; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

host  Specifies  the  network  address  of  the  host  machine  to  be  added. 

Description 

XAddHost  adds  the  specified  host  to  the  access  control  list  for  the  server  specified  by  dis 
play.  The  access  control  list  is  a  primitive  security  feature  that  allows  access  to  the  server 
only  by  other  machines  listed  in  a  file  on  the  machine  running  the  server.  On  UNIX-based  sys 
tems,  this  file  is  called  letclX?. hosts,  where  ?  is  the  number  of  the  server. 

The  application  that  calls  XAddHost  and  the  server  whose  list  is  being  updated  must  be  run 
ning  on  the  same  host  machine. 

The  address  data  must  be  a  valid  address  for  the  type  of  network  in  which  the  server  oper 
ates,  as  specified  in  the  family  member.  Internet,  DECnet  and  ChaosNet  networks  are  cur 
rently  supported. 

For  TCP/IP,  the  address  should  be  in  network  byte  order.  For  the  DECnet  family,  the  server 
performs  no  automatic  swapping  on  the  address  bytes.  A  Phase  IV  address  is  two  bytes  long. 
The  first  byte  contains  the  least  significant  eight  bits  of  the  node  number.  The  second  byte  con 
tains  the  most  significant  two  bits  of  the  node  number  in  the  least  significant  two  bits  of  the 
byte,  and  the  area  in  the  most  significant  six  bits  of  the  byte. 

For  more  information  on  access  control,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 

Structures 

typedef  struct  { 

int  family;  /*  for  example  Familylnternet  */ 

int  length;  /*  length  of  address,  in  bytes  */ 

char  *address;         /*  pointer  to  where  to  find  the  bytes  */ 

}  XHostAddress; 

/*  The  following  constants  for  family  member  */ 

#define  Familylnternet  0 

ttdefine  FamilyDECnet  1 

#define  FamilyChaos  2 

Errors 

BadAccess 
BadValue 
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Related  Commands 

XAddHosts, XDisableAccessControl, XEnableAccessControl, XListHosts, 
XRemoveHost, XRemoveHosts, XSetAccessControl. 
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Name 

XAddHosts  —  add  multiple  hosts  to  the  access  control  list. 

Synopsis 

XAddHosts ( display,  hosts,  num_hosts) 
Display  *display; 
XHost Address  * hosts; 
int  num_hosts; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

hosts  Specifies  each  host  that  is  to  be  added. 

n  um_h  osts       Specifies  the  number  of  hosts  that  are  to  be  added. 

Description 

XAddHosts  adds  each  specified  host  to  the  access  control  list  for  the  server  specified  by  dis 
play.  The  access  control  list  is  a  primitive  security  feature  that  allows  access  to  the  server 
only  by  other  machines  listed  in  a  file  on  the  machine  running  the  server.  On  UNIX  systems, 
this  file  is  letclX?. hosts,  where  ?  is  the  number  of  the  display. 

The  application  that  calls  XAddHosta  and  the  server  whose  list  is  being  updated  must  be  run 
ning  on  the  same  host  machine. 

The  address  data  must  be  a  valid  address  for  the  type  of  network  in  which  the  server  oper 
ates,  as  specified  by  the  family  member.  Internet,  DECnet  and  ChaosNet  networks  are  cur 
rently  supported. 

For  TCP/IP,  the  address  should  be  in  network  byte  order.  For  the  DECnet  family,  the  server 
performs  no  automatic  swapping  on  the  address  bytes.  A  Phase  IV  address  is  two  bytes  long. 
The  first  byte  contains  the  least  significant  eight  bits  of  the  node  number.  The  second  byte  con 
tains  the  most  significant  two  bits  of  the  node  number  in  the  least  significant  two  bits  of  the 
byte,  and  the  area  in  the  most  significant  six  bits  of  the  byte. 

For  more  information  on  access  control,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 

Structures 

typedef  struct  { 

int  family;  /*  for  example  Family  Internet  */ 

int  length;  /*  length  of  address,  in  bytes  */ 

char  *address;          /*  pointer  to  where  to  find  the  bytes  */ 

}  XHostAddress; 

/*  The  following  constants  for  family  member  */ 
tdefine  Familylnternet      0 
#define  FamilyDECnet        1 
#define  FamilyChaos        2 
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Errors 

BadAccess 
BadValue 

Related  Commands 

XAddHost, XDisableAccessControl, XEnableAccessControl, XListHosts, 
XRemoveHost, XRemoveHosts, XSetAccessControl. 


Xlib  Reference  Manual  39 


XAddPixel \ Xlib  _  lmages_ 

Name 

XAddPixel  —  add  a  constant  value  to  every  pixel  value  in  an  image. 

Synopsis 

XAddPixel (ximage,  value) 
Xlmage  *ximage ; 
unsigned  long  value; 

Arguments 

x image  Specifies  a  pointer  to  the  image  to  be  modified. 

value  Specifies  the  constant  value  that  is  to  be  added.   Valid  pixel  value  ranges 

depend  on  the  visual  used  to  create  the  image.   If  this  value  added  to  the 
existing  value  causes  an  overflow,  extra  bits  in  the  result  are  truncated. 

Description 

XAddPixel  adds  a  constant  value  to  every  pixel  value  in  an  image.  This  function  is  useful 
when  you  have  a  base  pixel  value  derived  from  the  allocation  of  color  resources  and  need  to 
manipulate  an  image  so  that  the  pixel  values  are  in  the  same  range. 

For  more  information  on  images,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
Structures 

typedef  struct   Xlmage  { 

int  width,  height;  /*  size  of  image  */ 

int  xoffset;  /*  number  of  pixels  offset  in  X  direction  */ 

int  format;  /*  XYBitmap,  XYPixmap,  ZPixmap  */ 

char  *data;  /*  pointer  to  image  data  */ 

int  byte_order;  /*  data  byte  order,  LSBFirst,  MSBFirst  */ 

int  bitmap_unit;  /*  quantity  of  scan  line  8,  16,  32  */ 

int  bitmap_bit_order;  /*  LSBFirst,  MSBFirst  */ 

int  bitmap_pad;  /*  8,  16,  32  either  XY  or  ZPixmap  */ 

int  depth;  /*  depth  of  image  */ 

int  bytes  per  line;  /*  accelerator  to  next  line  */ 

int  bits_per_pixel;  /*  bits  per  pixel  (ZPixmap)  */ 

unsigned  long  red_mask;  /*  bits  in  z  arrangment  */ 

unsigned  long  green  mask; 

unsigned  long  blue_mask; 

char  *obdata;  /*  hook  for  object  routines  to  hang  on  */ 

struct  funcs  {  /*  image  manipulation  routines  */ 

struct  _XImage  * (*create_image) (); 

int  (*destroy_image) (); 

unsigned  long  (*get_pixel) ( ) ; 

int  (*put_pixel) () ; 

struct  _XImage  * (*sub_image) (); 

int  (*add_pixel) (); 

}  f; 

}  Xlmage; 
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Xlib- Images  (continued)  XAddPixel 

Related  Commands 

ImageByteOrder,  XCreatelmage,  XDestroylmage,  XGetlmage,  XGetPixel, 
XGetSublmage,  XPutlmage,  XPutPixel,  XSub Image. 
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XAddToSaveSet  "\ 


XI ib- Save  Set  — 


Name 

XAddToSaveSet  —  add  a  window  to  the  client's  save-set. 

Synopsis 

XAddToSaveSet ( display,  w) 
Display  * display; 
Window  w; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  you  want  to  add  to  the  client's  save-set. 

Description 

XAddToSaveSet  adds  the  specified  window  to  the  client's  save-set. 

The  save-set  is  a  safety  net  for  windows  that  have  been  reparented  by  the  window  manager, 
usually  to  provide  a  titlebar  or  other  decorations  for  each  application.  When  the  window  man 
ager  dies  unexpectedly,  the  windows  in  the  save-set  are  reparented  to  their  closest  living  ances 
tor,  so  that  they  remain  alive.  See  Volume  One,  Chapter  13,  Other  Programming  Techniques, 
for  more  information  about  save-sets. 

Use  XRemoveFromSaveSet  to  remove  a  window  from  the  client's  save-set. 

Errors 

BadMat  ch          w  not  created  by  some  other  client. 

BadWindow 

Related  Commands 

XChangeSaveSet, XRemoveFromSaveSet. 
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-XHb- W,ndow  Manager  Him, /  XAIIOCCIaSSHint 

Name 

XAllocClassHint  —  allocate  an  XClassHint  structure. 

Synopsis 

XClassHint  *XAllocClassHint ( ) 

Availability 

Release  4  and  later. 

Description 

XAllocClassHint  allocates  and  returns  a  pointer  to  an  XClassHint  structure,  for  use  in 
calling  XSetWMProperties,  XGetClassHint,  or  XSetClassHint.  Note  that  the 
pointer  fields  in  the  XClassHint  structure  are  initially  set  to  NULL.  If  insufficient  memory  is 
available,  XAllocClassHint  returns  NULL.  To  free  the  memory  allocated  to  this  structure, 
useXFree. 

The  purpose  of  this  function  is  to  avoid  compiled-in  structure  sizes,  so  that  object  files  will  be 
binary  compatible  with  later  releases  that  may  have  new  members  added  to  structures. 

For  more  information,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Structures 

typedef   struct    { 

char    *res_name; 

char  *res_class; 
}  XClassHint; 

Related  Commands 

XGetClassHint, XSetClassHint, XSetWMProperties. 
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XANocColor  "\ Yll 

v Xlib  -  Color  Cells- 
Name 

XAllocColor  —  allocate  a  read-only  colormap  cell  with  closest  hardware-supported  color. 

Synopsis 

Status  XAllocColor ( display,  cmap,  colorcell_def) 
Display  * display; 
Colo  rmap  cmap ; 
XColor  *colorcell_def;  /*  SENDs  and  RETURNS  */ 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

cmap  Specifies  the  ID  of  the  colormap  in  which  the  colorcell  is  to  be  allocated. 

col  or eel  l_def 

Specifies  desired  RGB  values,  and  also  returns  the  pixel  value  and  the  RGB  val 
ues  actually  used  in  the  colormap. 

Description 

XAllocColor  returns  in  the  XColor  structure  the  pixel  value  of  a  read-only  (shareable) 
colorcell  with  the  closest  RGB  values  available  in  cmap.  XAllocColor  also  returns  the  red, 
green,  and  blue  values  actually  used. 

If  the  display  hardware  has  an  immutable  hardware  colormap,  the  entire  colormap  will  be  read 
only,  and  the  closest  cell  that  exists  will  be  returned.  Otherwise,  the  colormap  is  read/write, 
and  may  have  some  read/write  cells,  some  read-only  cells,  and  some  unallocated  cells.  If  a 
read-only  cell  exists  that  matches  the  requested  RGB  values,  that  cell  is  returned.  If  no  match 
ing  cell  exists  but  there  are  unallocated  cells,  a  cell  is  allocated  to  match  the  specified  RGB  val 
ues.  If  no  matching  cell  exists  and  there  are  no  unallocated  cells,  XAllocColor  returns  a 
Status  of  zero  (in  read/write  colormaps,  it  does  not  return  the  closest  available  read-only 
colorcell  that  has  already  been  allocated).  If  it  succeeds,  XAllocColor  returns  nonzero. 

Note  that  colorcell_def  stores  both  the  requested  color  when  XAllocColor  is  called 
and  the  result  when  XAllocColor  returns. 

XAllocColor  does  not  use  or  affect  the  flags  member  of  the  XColor  structure. 
For  more  information,  see  Volume  One,  Chapter  7,  Color. 

Structures 

typedef  struct  { 

unsigned  long  pixel; 

unsigned  short  red,  green,  blue; 

char  flags;  /*  DoRed,  DoGreen,  DoBlue  */ 

char  pad; 
}  XColor; 

Errors 

BadColormap 
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Xlib  -  Color  Cells  (continued)  XAIIOCColor 

Related  Commands 

BlackPixel, WhitePixel, XAllocColorCells, XAllocColorPlanes, XAlloc- 
NamedColor, XFreeColors, XLookupColor,  XParseColor,  XQueryColor, 
XQueryColors, XStoreColor, XStoreColors,  XStoreNamedColor. 
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XAIIocColorCells 


X 


•Xlib- Color  Cells- 


Name 

XAIIocColorCells  —  allocate  read/write  (nonshared)  colorcells. 


Synopsis 

Status  XAIIocColorCells (display,  cmap, 

nplanes,  pixels ,  ncolors) 
Display  *display; 
Colo rmap  cmap ; 
Bool  contig; 

unsigned  long  plane_masks [nplanes] 
unsigned  int  nplanes; 
unsigned  long  pixels [ncolors] ; 
unsigned  int  ncolors; 


contig,  plane_masks, 


/*    RETURN 


/*  RETURN   pixel   values    */ 


Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

cmap  Specifies  the  ID  of  the  colormap  in  which  the  colorcell  is  to  be  allocated. 

contig  Specifies  a  boolean  value.   Pass  True  if  the  planes  must  be  contiguous  or 

False  if  the  planes  need  not  be  contiguous. 

plane_mask     Returns  an  array  of  plane  masks. 

nplanes  Specifies  the  number  of  plane  masks  returned  in  the  plane  masks  array.  Must 

be  nonnegative. 

pixels  Returns  an  array  of  pixel  values. 

ncolors  Specifies  the  number  of  pixel  values  returned  in  the  pixels  array.  Must  be 

positive. 

Description 

XAIIocColorCells  allocates  read/write  colorcells  in  a  read/write  colormap.  If  ncolors 
and  nplanes  are  requested,  then  ncolors  pixels  and  nplanes  plane  masks  are  returned. 
No  mask  will  have  any  bits  in  common  with  any  other  mask,  or  with  any  of  the  pixels.  By 
ORing  together  each  of  the  pixels  with  any  combination  of  the  plane_masks, 
ncolors*2(npla/ies)  distinct  pixels  can  be  produced.  For  Grayscale  or  Pseudocolor, 
each  mask  will  have  exactly  one  bit,  and  for  DirectColor  each  will  have  exactly  three  bits. 
If  contig  is  True,  then  if  all  plane  masks  are  ORed  together,  a  single  contiguous  set  of  bits 
will  be  formed  for  Grayscale  or  Pseudocolor  and  three  contiguous  sets  of  bits  (one 
within  each  pixel  subfield)  for  DirectColor.  The  RGB  values  of  the  allocated  entries  are 
undefined  until  set  with  XStoreColor,  XStoreColors,  or  XStoreNamedColor. 

Status  is  zero  on  failure,  and  nonzero  on  success. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 
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Xlib  -  Color  Cells  (continued)  XAIIOCColorCellS 

Errors 

BadColormap 

BadValue          npl an es  is  negative. 

n colors  is  not  positive. 

Related  Commands 

BlackPixel, WhitePixel, XAllocColor,  XAllocColorPlanes,  XAllocNamed- 
Color,  XFreeColors, XLookupColor, XParseColor, XQueryColor,  XQuery- 
Colors,  XStoreColor, XStoreColors,  XStoreNamedColor. 
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XAIIocColorPlanes  X v,, 

v XHb  -  Color  Cells- 
Name 

XAIIocColorPlanes  —  allocate  read/write  (nonshareable)  color  planes. 

Synopsis 

Status  XAIIocColorPlanes (display,  cmap,  contig,  pixels,  ncolors, 

nreds r  ngreens ,  nblues ,  rmask,  gmask,  bmask) 
Display  *display; 
Colo rmap  cmap ; 
Bool  contig; 

unsigned  long  pixels  [ncolors]  ;          /*  RETURN  */ 
int  n colors ; 

int  nreds,  ngreens,  nblues; 
unsigned  long  *rmask,  * gmask,  * bmask;   /*  RETURN  */ 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

cmap  Specifies  the  ID  of  the  colormap  to  be  used. 

contig          Specifies  a  boolean  value.   Pass  True  if  the  planes  must  be  contiguous  or 
False  if  the  planes  do  not  need  to  be  contiguous. 

pixels  Returns  an  array  of  pixel  values. 

7i  colors        Specifies  the  number  of  pixel  values  returned  in  the  pixels  array.  Must  be  posi 
tive. 

nreds  Specify  the  number  of  red,  green,  and  blue  planes  (shades).  Must  be  nonnega- 

ngreens         tive. 

nblues 

rmask  Return  bit  masks  for  the  red,  green,  and  blue  planes. 

gmask 

bmask 

Description 

If  ncolors,  nreds,  ngreens,  and  nblues  are  requested,  then  ncolors  pixels  are 
returned,  and  the  masks  have  nreds,  ngreens,  and  nblues  bits  set  to  1  respectively. 
Unique  pixel  values  are  generated  by  by  ORing  together  subsets  of  masks  with  each  item  in  the 
pixels  list  (pixels  does  not  by  itself  contain  pixel  values).  In  doing  this,  note  that 

nCOlorS*(  2  (nreds+ngreens+nblues)  )  distinct  pixel  ValuCS  aTC  allocated. 

If  contig  is  True,  then  each  mask  will  have  a  contiguous  set  of  bits.  No  mask  will  have  any 
bits  in  common  with  any  other  mask,  or  with  any  of  the  pixels.  For  DirectColor,  each 
mask  will  lie  within  the  corresponding  pixel  subfield. 

Note,  however,  that  there  are  actually  only  ncolors*(2nreds  )  independent  red  entries, 
ncolors~*(2nereens  )  independent  green  entries,  and  n  colors*  (2  nblues  )  independent  blue 
entries  in  the  colormap.  This  is  true  even  for  Pseudocolor.  This  does  not  cause  problems, 
though,  because  when  the  colormap  entry  for  a  pixel  value  is  changed  using  xstoreColors 
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Xlib  -  Color  Cells  (continued)  XAHocColorPlaneS 

or  XStoreNamedColor,  the  pixel  is  decomposed  according  to  rmask,  gmask,  and  bmask 
and  the  corresponding  pixel  subfield  entries  are  updated. 

Status  is  zero  on  failure,  and  nonzero  on  success. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 

Errors 

BadColormap 

BadValue          n colors  is  not  positive. 

At  least  one  of  nreds,  ngreens,  nbl  ues  is  negative. 

Related  Commands 

BlackPixel, WhitePixel, XAllocColor,  XAllocColorCells,  XAllocNamed- 
Color,  XFreeColors, XLookupColor, XParseColor, XQueryColor, XQuery- 
Colors, XStoreColor, XStoreColors, XStoreNamedColor. 
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XAIIoclconSize  V VI1I 

v Xlib  -  Window  Manager  Hints- 
Name 

XAllocIconSize  —  allocate  anxiconSize  structure. 

Synopsis 

XlconSize    *XAllocIconSize (  ) 

Availability 

Release  4  and  later. 

Description 

XAIIoclconSize  allocates  and  returns  a  pointer  to  an  XlconSize  structure,  for  use  in  cal 
ling  XGetlconSizes  or  XSetlconSizes.  Note  that  all  fields  in  the  XlconSize  struc 
ture  are  initially  set  to  zero.  If  insufficient  memory  is  available,  XAIIoclconSize  returns 
NULL.  To  free  the  memory  allocated  to  this  structure,  use  XFree. 

The  purpose  of  this  function  is  to  avoid  compiled-in  structure  sizes,  so  that  object  files  will  be 
binary  compatible  with  later  releases  that  may  have  new  members  added  to  structures. 

For  more  information,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Structures 

typedef  struct  { 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  heigh t_inc; 
}  XlconSize; 

Related  Commands 

XGetlconSizes, XSetlconSizes. 
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—Xlib -Color  Cells- 


J  XAIIocNamedColor 


Name 

XAIIocNamedColor  —  allocate  a  read-only  colorcell  from  color  name. 

Synopsis 

Status  XAIIocNamedColor (display,  cmap,  colorname , 

colorcell_def,  rgb_db_def) 
Display  * display; 
Colormap  cmap; 
char  * colorname; 

XColor  *colorcell_def;     /*  RETURN  */ 
XColor  *rgb_db_def;        /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

cmap  Specifies  the  ID  of  the  colormap  in  which  the  colorcell  will  be  allocated. 

colorname  Specifies  the  color  name  string  (for  example,  "red")  you  want.  Upper  or 
lower  case  does  not  matter.  The  string  should  be  in  ISO  LATIN- 1  encoding, 
which  means  that  the  first  128  character  codes  are  ASCII,  and  the  second  128 
character  codes  are  for  special  characters  needed  in  western  languages  other 
than  English. 

colorcell_def 

Returns  the  pixel  value  and  RGB  values  actually  used  in  the  colormap.  This 
is  the  closest  color  supported  by  the  hardware. 

rgb_db_def  Returns  the  exact  RGB  values  from  the  database  corresponding  to  the 
colorname  supplied. 

Description 

XAIIocNamedColor  determines  the  RGB  values  for  the  specified  colorname  from  the 
color  database,  and  then  allocates  a  read-only  colorcell  with  the  closest  color  available,  as 
described  under  XAllocColor.  Both  the  'exact'  database  definition  of  the  color,  and  the 
color  actually  allocated  are  returned.  If  the  colormap  is  not  full,  the  RGB  values  allocated  are 
the  closest  supported  by  the  hardware.  If  the  colormap  is  full,  and  is  a  StaticColor, 
DirectColor,  or  StaticGray  visual  class,  XAIIocNamedColor  returns  the  closest 
read-only  colorcell  already  allocated,  and  does  not  actually  create  or  set  any  new  colorcell.  If 
the  colormap  is  full  and  is  a  Pseudocolor,  TrueColor,  or  Grayscale  visual  class, 
XAIIocNamedColor  fails  and  returns  zero. 

XAIIocNamedColor  returns  a  Status  of  zero  if  colorname  was  not  found  in  the  data 
base  or  if  the  color  could  not  be  allocated.  The  function  returns  nonzero  when  it  succeeds. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 
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X AllocNamedColor  (continued)  Xlib  -  Color  Cells 

Errors 

BadColormap 
BadName 

Structures 

typedef  struct  { 

unsigned  long  pixel; 

unsigned  short  red,  green,  blue; 

char  flags;  /*  DoRed,  DoGreen,  DoBlue  */ 

char  pad; 
}  XColor; 

Related  Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor- 
Planes, XFreeColors, XLookupColor, XParseColor, XQueryColor, XQuery- 
Colors, XStoreColor, XStoreColors, XStoreNamedColor. 
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-XMb-WmdowManager  Him, '  XAIIOCSizeHintS 

Name 

XAllocSizeHints  — allocate  an  XSizeHints  structure. 

Synopsis 

XSizeHints  *XAllocSizeHints ( ) 

Availability 

Release  4  and  later. 

Description 

XAllocSizeHints  allocates  and  returns  a  pointer  to  an  XSizeHints  structure,  for  use  in 
calling  XSetWMProperties,XSetWMNormalHints,orXGetWMNormalHints.  Note 
that  all  fields  in  the  XSizeHints  structure  are  initially  set  to  zero.  If  insufficient  memory  is 
available,  XAllocSizeHints  returns  NULL.  To  free  the  memory  allocated  to  this  structure, 
use  XFree. 

The  purpose  of  this  function  is  to  avoid  compiled-in  structure  sizes,  so  that  object  files  will  be 
binary  compatible  with  later  releases  that  may  have  new  members  added  to  structures. 

For  more  information,  see  Volume  One,  Chapter  W,Interclient  Communication. 
Structures 

typedef  struct  { 

long  flags;      /*  marks  which  fields  in  this  structure  are  defined  */ 

int  x,  y;        /*  Obsolete  */ 

int  width,  height;   /*  Obsolete  */ 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x;       /*  numerator  */ 

int  y;       /*  denominator  */ 
}  min_aspect,  max_aspect; 
int  base_width,  base_height ; 
int  win_gravity; 
}  XSizeHints; 

Related  Commands 

XGetWMNormalHints, XSetWMNormalHints, XSetWMProperties. 
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XAIIocStandardColormap  V Vl. 

v Xhb  -  Window  Manager  Hints- 
Name 

XAIIocStandardColormap  — allocate  an  XStandardColormap  structure. 

Synopsis 

XStandardColormap  *XAllocStandardColormap ( ) 

Availability 

Release  4  and  later. 

Description 

XAIIocStandardColormap  allocates  and  returns  a  pointer  to  an  XStandardColormap 
structure  for  use  in  calling  XGetRGBColormaps  or  XSetRGBColormaps.  Note  that  all 
fields  in  the  XStandardColormap  structure  are  initially  set  to  zero.  If  insufficient  memory 
is  available,  XAIIocStandardColormap  returns  NULL.  To  free  the  memory  allocated  to 
this  structure,  use  XFree. 

The  purpose  of  this  function  is  to  avoid  compiled-in  structure  sizes,  so  that  object  files  will  be 
binary  compatible  with  later  releases  that  may  have  new  members  added  to  structures. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 
Structures 

/*  value  for  killid  field  */ 

#define   ReleaseByFreeingColormap      (  (XID)  1L) 

typedef  struct  { 

Colormap  colormap; 

unsigned  long  red_max; 

unsigned  long  red_mult; 

unsigned  long  green_max; 

unsigned  long  green_mult ; 

unsigned  long  blue__max; 

unsigned  long  blue_mult; 

unsigned  long  base_pixel; 

VisuallD  visualid; 

XID  killid; 
}  XStandardColormap; 

Related  Commands 

XGetRGBColormaps, XSetRGBColormaps. 
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-Xlib-  Window  Manager  Hints '  XAIIOCWMHmtS 

Name 

XAllocWMHints  —  allocate  an  XWMHints  structure. 

Synopsis 

XWMHints  *XAllocWMHints ( ) 

Availability 

Release  4  and  later. 

Description 

The  XAllocWMHints  function  allocates  and  returns  a  pointer  to  an  XWMHints  structure,  for 
use  in  calling  XSetWMProperties,  XSetWMHints,  or  XGetWMHints.  Note  that  all  fields 
in  the  XWMHints  structure  are  initially  set  to  zero.  If  insufficient  memory  is  available, 
XAllocWMHints  returns  NULL.  To  free  the  memory  allocated  to  this  structure,  use  XFree. 

The  purpose  of  this  function  is  to  avoid  compiled-in  structure  sizes,  so  that  object  files  will  be 
binary  compatible  with  later  releases  that  may  have  new  members  added  to  structures. 

For  more  information,  see  Volume  One,  Chapter  10,  Interdient  Communication. 
Structures 

typedef   struct    { 

long   flags;  /*   marks   which   fields    in   this   structure   are   defined   */ 

Bool    input;  /*    does   this   application   rely   on   the   window  manager 

to   get   keyboard   input?    */ 

int    initial_state;         /*    see   below   */ 

Pixmap   icon_pixmap;      /*   pixmap   to  be   used   as    icon    */ 

Window   icon_window;      /*    window  to  be   used   as    icon    */ 

int    icon_x,    icon_y;      /*    initial   position   of   icon    */ 

Pixmap   icon_mask;  /*   pixmap   to  be   used   as   mask   for   icon_pixmap    */ 

XID    window_group;  /*    id   of   related   window   group    */ 

/*    this    structure   may  be   extended   in   the    future    */ 
}    XWMHints; 

Related  Commands 

XGetWMHints, XSetWMHints, XSetWMProperties. 
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Name 

XAIIowEvents  —  control  the  behavior  of  keyboard  and  pointer  events  when  these  resources  are 


Synopsis 

XAIIowEvents  ( display,  event_mode,  time) 
Display  *display; 
int  event_/node; 
Time  time; 


Arguments 

display 
event  mode 


Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

Specifies  the  event  mode.  Pass  one  of  these  constants:  AsyncPointer, 
SyncPointer,  AsyncKeyboard,  SyncKeyboard,  ReplayPointer, 
ReplayKeyboard,  AsyncBoth,  or  SyncBoth. 

time  Specifies  the  time  when  the  grab  should  take  place.  Pass  either  a  timestamp, 

expressed  in  milliseconds,  or  the  constant  Cur  rent  Time. 

Description 

XAIIowEvents  releases  the  events  queued  in  the  server  since  the  last  XAIIowEvents  call 
for  the  same  device  and  by  the  same  client.  Events  are  queued  in  the  server  (not  released  to 
Xlib  to  propagate  into  Xlib's  queues)  only  when  the  client  has  caused  a  device  to  "freeze"  (by 
grabbing  the  device  with  mode  GrabModeSync).  The  request  has  no  effect  if  time  is  earlier 
than  the  last-grab  time  or  later  than  the  current  server  time. 

The  event_mode  argument  controls  what  device  events  are  released  for  and  just  how  and 
when  they  are  released.  The  event_mode  is  interpreted  as  follows: 

AsyncPointer  If  XAIIowEvents   is  called   with  AsyncPointer  while  the 

pointer  is  frozen  by  the  client,  pointer  event  processing  resumes  nor 
mally,  even  if  the  pointer  is  frozen  twice  by  the  client  on  behalf  of 
two  separate  grabs.  AsyncPointer  has  no  effect  if  the  pointer  is 
not  frozen  by  the  client,  but  the  pointer  need  not  be  grabbed  by  the 
client. 

AsyncKeyboard  If  XAIIowEvents  is  called  with  AsyncKeyboard  while  the  key 

board  is  frozen  by  the  client,  keyboard  event  processing  resumes 
normally,  even  if  the  keyboard  is  frozen  twice  by  the  client  on  behalf 
of  two  separate  grabs.  AsyncKeyboard  has  no  effect  if  the  key 
board  is  not  frozen  by  the  client,  but  the  keyboard  need  not  be 
grabbed  by  the  client. 

SyncPointer  If  XAIIowEvents  is  called  with  SyncPointer  while  the  pointer 

is  frozen  by  the  client,  normal  pointer  event  processing  continues 
until  the  next  ButtonPress  or  But tonRe lease  event  is 
reported  to  the  client.  At  this  time,  the  pointer  again  appears  to 
freeze.  However,  if  the  reported  event  causes  the  pointer  grab  to  be 
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XAIIowEvents 


SyncKeyboard 


ReplayPointer 


ReplayKeyboard 


SyncBoth 


AsyncBoth 


released,  then  the  pointer  does  not  freeze,  which  is  the  case  when  an 
automatic  grab  is  released  by  a  ButtonRelease  or  when  XGrab- 
Button  or  XGrabKey  has  been  called  and  the  specified  key  or  but 
ton  is  released.  SyncPointer  has  no  effect  if  the  pointer  is  not 
frozen  or  not  grabbed  by  the  client. 

If  XAIIowEvents  is  called  with  SyncKeyboard  while  the  key 
board  is  frozen  by  the  client,  normal  keyboard  event  processing  con 
tinues  until  the  next  KeyPress  or  KeyRelease  event  is  reported 
to  the  client.  At  this  time,  the  keyboard  again  appears  to  freeze. 
However,  if  the  reported  event  causes  the  keyboard  grab  to  be 
released,  then  the  keyboard  does  not  freeze,  which  is  the  case  when 
an  automatic  grab  is  released  by  a  ButtonRelease  or  when 
XGrabButton  or  XGrabKey  has  been  called  and  the  specified  key 
or  button  is  released.  SyncKeyboard  has  no  effect  if  the  keyboard 
is  not  frozen  or  not  grabbed  by  the  client. 

This  symbol  has  an  effect  only  if  the  pointer  is  grabbed  by  the  client 
and  thereby  frozen  as  the  result  of  an  event.  In  other  words, 
XGrabButton  must  have  been  called  and  the  selected  button/key 
combination  pressed,  or  an  automatic  grab  (initiated  by  a  Button- 
Press)  must  be  in  effect,  or  a  previous  XAIIowEvents  must  have 
been  called  with  mode  SyncPointer.  If  the  pointer_mode  of 
the  XGrabPointer  was  GrabModeSync,  then  the  grab  is 
released  and  the  releasing  event  is  processed  as  if  it  had  occurred 
after  the  release,  ignoring  any  passive  grabs  at  or  above  in  the  hierar 
chy  (towards  the  root)  on  the  grab-window  of  the  grab  just  released. 

This  symbol  has  an  effect  only  if  the  keyboard  is  grabbed  by  the  cli 
ent  and  if  the  keyboard  is  frozen  as  the  result  of  an  event.  In  other 
words,  XGrabKey  must  have  been  called  and  the  selected  key  com 
bination  pressed,  or  a  previous  XAIIowEvents  must  have  been 
called  with  mode  SyncKeyboard.  If  the  pointer_mode  or 
keyboard_mode  of  the  XGrabKey  was  GrabModeSync,  then 
the  grab  is  released  and  the  releasing  event  is  processed  as  if  it  had 
occurred  after  the  release,  ignoring  any  passive  grabs  at  or  above  in 
the  hierarchy  (towards  the  root). 

SyncBoth  has  the  effect  described  for  both  SyncKeyboard  and 
SyncPointer.  SyncBoth  has  no  effect  unless  both  pointer  and 
keyboard  are  frozen  by  the  client.  If  the  pointer  or  keyboard  is  fro 
zen  twice  by  the  client  on  behalf  of  two  separate  grabs,  SyncBoth 
"thaws"  for  both  (but  a  subsequent  freeze  for  SyncBoth  will  only 
freeze  each  device  once). 

AsyncBoth  has  the  effect  described  for  both  AsyncKeyboard 
and  AsyncPointer.  AsyncBoth  has  no  effect  unless  both 
pointer  and  keyboard  are  frozen  by  the  client.  If  the  pointer  and  the 
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keyboard  were  frozen  by  the  client,  or  if  both  are  frozen  twice  by 
two  separate  grabs,  event  processing  (for  both  devices)  continues 
normally.  If  a  device  is  frozen  twice  by  the  client  on  behalf  of  the 
two  separate  grabs,  AsyncBoth  releases  events  for  both. 

AsyncPointer,  SyncPointer,  and  ReplayPointer  have  no  effect  on  the  processing  of 
keyboard  events.  AsyncKeyboard,  SyncKeyboard,  and  ReplayKeyboard  have  no 
effect  on  the  processing  of  pointer  events. 

It  is  possible  for  both  a  pointer  grab  and  a  keyboard  grab  (by  the  same  or  different  clients)  to  be 
active  simultaneously.  If  a  device  is  frozen  on  behalf  of  either  grab,  no  event  processing  is  per 
formed  for  the  device.  It  is  also  possible  for  a  single  device  to  be  frozen  because  of  both  grabs. 
In  this  case,  the  freeze  must  be  released  on  behalf  of  both  grabs  before  events  will  be  released. 

For  more  information  on  event  handling,  see  Volume  One,  Chapter  9,  The  Keyboard  and 
Pointer. 

Errors 

BadValue          Invalid  mode  constant. 

Related  Commands 

QLength, XChecklf Event, XCheckMaskEvent,  XCheckTypedEvent,  XCheck- 
TypedWindowEvent,  XCheckWindowEvent, XEventsQueued, XGetlnputFocus, 
XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event,  XPending,  XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus, XSynchronize, XWindowEvent. 
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Name 

XAutoRepeatOff  —  turn  off  the  keyboard  auto-repeat  keys. 

Synopsis 

XAutoRepeatOff (display) 
Display    *display; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

Description 

XAutoRepeatOff  turns  off  auto-repeat  for  the  keyboard.  It  sets  the  keyboard  so  that  holding 
any  non-modal  key  down  will  not  result  in  multiple  events. 

Related  Commands 

XAutoRepeatOn, XBell, XChangeKeyboardControl, XGetDef ault, XGet- 
KeyboardControl,  XGet Point erControl. 


Xlib  Reference  Manual 


XAutoRepeatOn  \. 
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Name 

XAutoRepeatOn  —  turn  on  the  keyboard  auto-repeat  keys. 

Synopsis 

XAutoRepeatOn  (display) 
Display    *display; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

Description 

XAutoRepeatOn  sets  the  keyboard  to  auto-repeat;  that  is,  holding  any  non-modal  key  down 
will  result  in  multiple  KeyPress  and  KeyRelease  event  pairs  with  the  same  keycode 
member.  Keys  such  as  Shift  Lock  will  still  not  repeat. 

Related  Commands 

XAutoRepeatOf f , XBell,  XChangeKeyboardControl, XGetDef ault, XGet- 
KeyboardControl,  XGetPointerControl. 
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Name 

XBell  —  ring  the  bell  (Control  G). 

Synopsis 

XBe  1 1  (  di  spl  ay,  per  can  t ) 
Display  *display; 
int  percent; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

percent  Specifies  the  volume  for  the  bell,  relative  to  the  base  volume  set  with 
XChangeKeyboardControl.  Possible  values  are  -100  (off),  through  0 
(base  volume),  to  100  (loudest)  inclusive. 

Description 

Rings  the  bell  on  the  keyboard  at  a  volume  relative  to  the  base  volume,  if  possible,  percent 
can  range  from  -100  to  100  inclusive  (else  a  BadValue  error).  The  volume  at  which  the  bell 
is  rung  when  percent  is  nonnegative  is: 

volume   =   base    -    [  (base    *    percent)    /    100]    +   percent 
and  when  percent  is  negative: 

volume    =   base    +    [ (base    *   percent)    /    100] 

To  change  the  base  volume  of  the  bell,  set  the  bell_percent  variable  of  XChange 
KeyboardControl. 

Errors 

BadValue    percent  <  -100  or  percent  >100. 

Related  Commands 

XAutoRepeatOf f , XAutoRepeatOn, XChangeKeyboardControl, XGetDef ault, 
XGetKeyboardControl, XGet Point erControl. 
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Name 

XChangeActivePointerGrab  —  change  the  parameters  of  an  active  pointer  grab. 

Synopsis 

XChangeActivePointerGrab (display,  event_mask,  cursor,  time) 
Display  *display; 
unsigned,  int  event_mask ; 
Cursor  cursor; 
Time  time; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

event_mask  Specifies  which  pointer  events  are  reported  to  the  client.  This  mask  is  the  bit 
wise  OR  of  one  or  more  of  these  pointer  event  masks:  ButtonPressMask, 
ButtonReleaseMask,  EnterWindowMask,  LeaveWindowMask, 
PointerMotionMask,  PointerMotionHintMask,  Buttonl- 
MotionMask,  Button2MotionMask,  ButtonSMotionMask,  But- 
ton4MotionMask,  ButtonSMotionMask,  ButtonMotionMask, 
KeymapStateMask. 

cursor  Specifies  the  cursor  that  is  displayed.  A  value  of  None  will  keep  the  current 

cursor. 

time  Specifies  the  time  when  the  grab  should  take  place.  Pass  either  a  timestamp, 

expressed  in  milliseconds,  or  the  constant  CurrentTime. 

Description 

XChangeActivePointerGrab  changes  the  characteristics  of  an  active  pointer  grab,  if  the 
specified  time  is  no  earlier  than  the  last  pointer  grab  time  and  no  later  than  the  current  X  server 
time.  XChangeActivePointerGrab  has  no  effect  on  the  passive  parameters  of  XGrab- 
Button,  or  the  automatic  grab  that  occurs  between  ButtonPress  and  ButtonRelease. 

event_mask  is  always  augmented  to  include  ButtonPress  and  ButtonRelease. 

For  more  information  on  pointer  grabbing,  see  Volume  One,  Chapter  9,  The  Keyboard  and 
Pointer. 

Errors 

BadCursor 

BadValue          The  event_mask  argument  is  invalid. 

Related  Commands 

XChangePointerControl, XGetPointerControl, XGetPointerMapping, 
XGrabPointer, XQueryPointer, XSetPointerMapping, XUngrabPointer, 
XWarpPointer. 
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f  XChangeGC 


Name 

XChangeGC  —  change  the  components  of  a  given  graphics  context. 

Synopsis 

XChangeGC (display,  gc ,  valuemask,  values) 
Display  *display; 
GC  gc; 

unsigned  long  valuemask; 
XGCValues  *  values; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

gc  Specifies  the  graphics  context. 

valuemask        Specifies  the  components  in  the  graphics  context  that  you  want  to  change. 
This  argument  is  the  bitwise  OR  of  one  or  more  of  the  GC  component  masks. 

val  ues  Specifies  a  pointer  to  the  XGCValues  structure. 

Description 

XChangeGC  changes  any  or  all  of  the  components  of  a  GC.  The  valuemask  specifies  which 
components  are  to  be  changed;  it  is  made  by  combining  any  number  of  the  mask  symbols  listed 
in  the  Structures  section  using  bitwise  OR  (|).  The  values  structure  contains  the  values  to  be 
set.  These  two  arguments  operate  just  like  they  do  in  XCreateGC.  Changing  the 
clip_mask  overrides  any  previous  XSetClipRectangles  request  for  this  GC.  Changing 
the  dash_of  f  set  or  dash_list  overrides  any  previous  XSetDashes  request  on  this  GC. 

Since  consecutive  changes  to  the  same  GC  are  buffered,  there  is  no  performance  advantage  to 
using  this  routine  over  the  routines  that  set  individual  members  of  the  GC. 

Even  if  an  error  occurs,  a  subset  of  the  components  may  have  already  been  altered. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context,  and  Chapter  6, 
Drawing  Graphics  and  Text. 

Structures 

typedef  struct  { 

int  function;  /*  logical  operation  */ 

unsigned  long  plane_mask;  /*  plane  mask  */ 

unsigned  long  foreground;  /*  foreground  pixel  */ 

unsigned  long  background;  /*  background  pixel  */ 

int  line_width;  /*  line  width  */ 

int  line  style;  /*  LineSolid,  LineOnOf fDash,  LineDoubleDash  */ 

int  cap_style;  /*  CapNotLast,  CapButt,  CapRound,  CapPro jecting  */ 

int  join  style;  /*  JoinMiter,  JoinRound,  JoinBevel  */ 

int  fill~style;  /*  FillSolid,  FillTiled,  FillStippled  */ 

int  fill_rule;  /*  EvenOddRule,  WindingRule  */ 

int  arc_mode;  /*  ArcChord,  ArcPieSlice  */ 

Pixmap  tile;  /*  tile  pixmap  for  tiling  operations  */ 

Pixmap  stipple;  /*  stipple  1  plane  pixmap  for  stipping  */ 

int  ts  x  origin;  /*  offset  for  tile  or  stipple  operations  */ 
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int  ts_y_origin; 
Font  font; 
int  subwindow_mode; 
Bool  graphics  exposures; 
int  clip_x_origin; 
int  clip_y_origin; 
Pixmap  clip_mask; 
int  dash_offset; 
char  dashes; 
}  XGCValues; 


/*  default  text  font  for  text  operations  */ 

/*  ClipByChildren,  Includelnferiors  */ 

/*  generate  events  on  XCopy,  Area,  XCopyPlane*/ 

/*  origin  for  clipping  */ 

/*  bitmap  clipping;  other  calls  for  rects  */ 

/*  patterned/dashed  line  information  */ 


#define 

GCFunction               (1L«0) 

#define 

GCPlaneMask              (1L«1) 

#define 

GCForeground             (1L«2) 

#define 

GCBackground             (1L«3) 

#define 

GCLineWidth              (1L«4) 

#def  ine 

GCLineStyle               (1L«5) 

#define 

GCCapStyle                (1L«6) 

#def  ine 

GCJoinStyle              (1L«7) 

#define 

GCFillStyle              (1L«8) 

#define 

GCFillRule               (1L«9) 

#define 

GCTile                   (1L«10) 

#define 

GCStipple                (1L«11) 

#define 

GCTileStipXOrigin        (1L«12) 

#def  ine 

GCTileStipYOrigin        (1L«13) 

#define 

GCFont                    (1L«14) 

#def  ine 

GCSubwindowMode          (1L«15) 

#define 

GCGraphicsExposures      (1L«16) 

#def  ine 

GCClipXOrigin            (1L«17) 

#define 

GCClipYOrigin            (1L«18) 

#define 

GCClipMask                (1L«19) 

#def  ine 

GCDashOffset             (1L«20) 

#define 

GCDashList               (1L«21) 

#def  ine 

GCArcMode                (1L«22) 

Errors 

BadAlloc 

BadFont 

BadGC 

BadMatch 

BadPixmap 

BadValue 

Related  Commands 

Def aultGC, XCopyGC, XCreateGC,  XFreeGC,  XGContextFromGC, XGetGCValues, 
XSetArcMode, XSetBackground,  XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane- 
Mask,  XSetRegion, XSetState,  XSetStipple,  XSetSubwindowMode, XSet- 
TSOrigin. 
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J  XChangeKeyboardControl 


Name 

XChangeKeyboardControl  —  change  the  keyboard  preferences  such  as  key  click. 

Synopsis 

XChangeKeyboardControl (display,  value_mask ,  values) 
Display  *  display; 
unsigned  long  value_mask; 
XKeyboardControl  *  values; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

value_mask     Specifies  a  mask  composed  of  ORed  symbols  from  the  table  shown  in  the 
Structures  section  below,  specifying  which  fields  to  set. 

values  Specifies  the  settings  for  the  keyboard  preferences. 

Description 

XChangeKeyboardControl  sets  user  preferences  such  as  key  click,  bell  volume  and  dura 
tion,  light  state,  and  keyboard  auto-repeat.  Changing  some  or  all  these  settings  may  not  be  pos 
sible  on  all  servers. 

The  value_mask  argument  specifies  which  values  are  to  be  changed;  it  is  made  by  combin 
ing  any  number  of  the  mask  symbols  listed  in  the  Structures  section  using  bitwise  OR  (|). 

The  values  structure  contains  the  values  to  be  set,  as  follows: 

key_click_percent  sets  the  volume  for  key  clicks  between  0  (off)  and  100  (loud)  inclu 
sive.  Setting  to  -1  restores  the  default. 

bell_percent  sets  the  base  volume  for  the  bell  between  0  (off)  and  100  (loud)  inclusive. 
Setting  to  -1  restores  the  default. 

bell  _jpitch  sets  the  pitch  (specified  in  Hz)  of  the  bell.  Setting  to  -1  restores  the  default. 

bell_duration  sets  the  duration  (specified  in  milliseconds)  of  the  bell.  Setting  to  -1 
restores  the  default. 

led__mode  is  either  LedModeOn  or  LedModeOf  f .  led  is  a  number  between  1  and  32  inclu 
sive  that  specifies  which  light's  state  is  to  be  changed.  If  both  led_mode  and  led  are  speci 
fied,  then  the  state  of  the  LED  specified  in  led  is  changed  to  the  state  specified  in  led_mode. 
If  only  led_mode  is  specified,  then  all  the  LEDs  assume  the  value  specified  by  led_mode. 

auto_repeat_mode  is  either  AutoRepeatModeOn,  AutoRepeatModeOf  f ,  or  Auto- 
RepeatModeDef ault.  key  is  a  keycode  between  7  and  255  inclusive.  If  both 
auto_repeat_mode  and  key  are  specified,  then  the  auto-repeat  mode  of  the  key  specified 
by  key  is  set  as  specified  by  auto_repeat_mode.  If  only  auto_repeat_mode  is  speci 
fied,  then  the  global  auto  repeat  mode  for  the  entire  keyboard  is  changed,  without  affecting  the 
settings  for  each  key.  If  the  auto_repeat_mode  is  AutoRepeatModeDe fault  for 
either  case,  the  key  or  the  entire  keyboard  is  returned  to  its  default  setting  for  the  server,  which 
is  normally  to  have  all  non-modal  keys  repeat. 
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When  a  key  is  being  used  as  a  modifier  key,  it  does  not  repeat  regardless  of  the  individual  or 
global  auto  repeat  mode. 

The  order  in  which  the  changes  are  performed  is  server-dependent,  and  some  may  be  completed 
when  another  causes  an  error. 

For  more  information  on  user  preferences,  see  Volume  One,  Chapter  9,  The  Keyboard  and 
Pointer. 

Structures 

/*  masks  for  ChangeKeyboardControl  */ 

#define  KBKeyClickPercent  (1L«0) 

#define  KBBellPercent  (1L«1) 

#define  KBBellPitch  (1L«2) 

#define  KBBellDuration  (1L«3) 

#define  KBLed  (1L«4) 

#define  KBLedMode  (1L«5) 

tdefine  KBKey  (1L«6) 

tdefine  KBAutoRepeatMode  (1L«7) 

/*  structure  for  ChangeKeyboardControl  */ 

typedef  struct  { 

int  key_click_percent; 

int  bell_percent; 

int  bell_pitch; 

int  bell_duration; 

int  led; 

int  led_mode;  /*  LedModeOn  or  LedModeOff  */ 

int  key; 

int  auto_repeat_mode;      /*  AutoRepeatModeOf f ,  AutoRepeatModeOn, 

AutoRepeatModeDefault  */ 
}  XKeyboardControl; 

Errors 

BadMatch          values,  key  specified  but  values,  auto .  repeat  .mode  not  specified, 
values .  led  specified  but  values .  led_mode  not  specified. 

BadValue  values. key_click_percent    <  -1. 

values. be ll_percent    <  -1. 
values.  bell_j3itch   <  -I. 
values.bell_duration   <  -1. 

Related  Commands 

XAutoRepeatOf  f ,  XAutoRepeatOn,  XBell,  XGetDef  ault,  XGetKeyboard- 
Control, XGetPointerControl. 
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Name 

XChangeKeyboardMapping  —  change  the  keyboard  mapping. 
Synopsis 

XChangeKeyboardMapping (display,    first_code,    keysyms_per_code, 

keysyms,    num_codes) 
Display    * display; 
int    first_keycode; 
int    keysyms_per_keycode; 
KeySym   * keysyms; 
int    num_keycodes ; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

fi  rs  t_keycode 

Specifies  the  first  keycode  that  is  to  be  changed. 

key syms_per_key code 

Specifies  the  number  of  keysyms  that  the  caller  is  supplying  for  each  keycode. 

keysyms         Specifies  a  pointer  to  the  list  of  keysyms. 

num_key codes 

Specifies  the  number  of  keycodes  that  are  to  be  changed. 

Description 

Starting  with  first_keycode,  XChangeKeyboardMapping  defines  the  keysyms  for  the 
specified  number  of  keycodes.  The  symbols  for  keycodes  outside  this  range  remain  unchanged. 
The  number  of  elements  in  the  keysyms  list  must  be  a  multiple  of  key syms_per_key code 
(else  a  BadLength  error).  The  specified  first_keycode  must  be  greater  than  or  equal  to 
min_keycode  supplied  at  connection  setup  and  stored  in  the  display  structure  (else  a  Bad- 
Value  error).  In  addition,  the  following  expression  must  be  less  than  or  equal  to  max_key- 
code  field  of  the  Display  structure  (else  a  BadValue  error): 

max_keycode  >=  first_keycode  +  (num_keycodes  /  key syms_per_key code)  -  1 

The  keysym  number  N  (counting  from  0)  for  keycode  K  has  an  index  in  the  keysyms  array 
(counting  from  0)  of  the  following  (in  keysyms): 

index    =    (K   -    first   keycode)    *    keysyms_per_keycode   +   N 

The  specified  keysyms^per_keycode  can  be  chosen  arbitrarily  by  the  client  to  be  large 
enough  to  hold  all  desired  symbols.  A  special  keysym  value  of  NoSymbol  should  be  used  to 
fill  in  unused  elements  for  individual  keycodes.  It  is  legal  for  NoSymbol  to  appear  in  nontrail- 
ing  positions  of  the  effective  list  for  a  keycode. 

XChangeKeyboardMapping  generates  a  MappingNotif  y  event,  sent  to  this  and  all  other 
clients,  since  the  keycode  to  keysym  mapping  is  global  to  all  clients. 
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Errors 

BadAlloc 

BadValue  first .  keycode  less  than  display->min_keycode. 

display->max_keycode  exceeded  (see  above). 

Related  Commands 

XDeleteModif  iermapEntry,  XFreeModif  iermap,  XGetKeyboardMapping, 
XGetModif ierMapping, XInsertModif iermapEntry,  XKeycodeToKeysym, 
XKeysymToKeycode, XKeysymToString, XLookupKeysym,  XLookupString, 
XNewModif  ierMap,  XQueryKeymap,  XRebindKeySym,  XRef reshKeyboard- 
Mapping,  XSetModif ierMapping,  XStringToKeysym. 
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— Xlib  -Pointers- 


J  XChangePointerControl 


Name 

XChangePointerControl  —  change  the  pointer  preferences. 

Synopsis 

XChangePointerControl (display,  do_accel ,  do_thresholdr 
accel_numerator,  accel_denominator,  threshold) 
Display  *display; 
Bool  do_accel ,  do_threshold; 
int  accel_numeratorf  accel_denominator; 
int  threshold; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

do_accel  Specifies  a  boolean  value  that  controls  whether  the  values  for  the 
accel_numerator  or  accel_denominator  are  set.  You  can  pass  one 
of  these  constants:  True  or  False. 

do_ thresh  old 

Specifies  a  boolean  value  that  controls  whether  the  value  for  the  threshold  is 
set.  You  can  pass  one  of  these  constants:  True  or  False. 

accel_numerator 

Specifies  the  numerator  for  the  acceleration  multiplier. 

accel_denominator 

Specifies  the  denominator  for  the  acceleration  multiplier. 

threshold       Specifies  the  acceleration  threshold. 

Description 

XChangePointerControl  defines  how  the  pointing  device  functions.  The  acceleration  is 
a  fraction  (accel_numerator/accel_denominator)  which  specifies  how  many  times 
faster  than  normal  the  sprite  on  the  screen  moves  for  a  given  pointer  movement.  Acceleration 
takes  effect  only  when  a  particular  pointer  motion  is  greater  than  threshold  pixels  at  once, 
and  only  applies  to  the  motion  beyond  threshold  pixels.  The  values  for  do_accel  and 
do_  thresh  old  must  be  nonzero  for  the  pointer  values  to  be  set;  otherwise,  the  parameters 
will  be  unchanged.  Setting  any  of  the  last  three  arguments  to  -1  restores  the  default  for  that 
argument. 

The  fraction  may  be  rounded  arbitrarily  by  the  server. 
Errors 

BadValue  accel_de/iomiriator  isO. 

Negative  value  for  do_accel  or  do_threshold. 
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Related  Commands 

XChangeActivePointerGrab, XGetPointerControl,  XGetPointerMapping, 
XGrabPointer, XQueryPointer, XSetPointerMapping,  XUngrabPointer, 
XWarpPointer. 


70  Xlib  Reference  Manual 


—  Xlib -Properties- 


J  XChangeProperty 


Name 

XChangeProperty  —  change  a  property  associated  with  a  window. 

Synopsis 

XChangeProperty (display,  w,  property,  type,  format,  mode, 

data,  nelements) 
Display  * display; 
Window  w; 

Atom  property,  type; 
int  format; 
int  mode ; 

unsigned  char  *data; 
int  nelements; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

w  Specifies  the  ID  of  the  window  whose  property  you  want  to  change, 

property  Specifies  the  property  atom. 

type  Specifies  the  type  of  the  property.  X  does  not  interpret  the  type,  but  simply 

passes  it  back  to  an  application  that  later  calls  XGet Property. 

format  Specifies  whether  the  data  should  be  viewed  as  a  list  of  8-bit,  16-bit,  or  32-bit 

quantities.  This  information  allows  the  X  server  to  correctly  perform  byte- 
swap  operations  as  necessary.  If  the  format  is  16-bit  or  32-bit,  you  must 
explicitly  cast  your  data  pointer  to  a  (char  *)  in  the  call  to  XChange 
Property.  Possible  values  are  8, 16,  and  32. 

mode  Specifies   the  mode  of  the  operation.    Possible  values  are  PropMode- 

Replace,  PropModePrepend,  PropModeAppend,  or  no  value. 

data  Specifies  the  property  data. 

n  el  emen  t  s        Specifies  the  number  of  elements  in  the  property. 

Description 

XChangeProperty  changes  a  property  and  generates  PropertyNotify  events  if  they 
have  been  selected. 

XChangeProperty  does  the  following  according  to  the  mode  argument: 

•  PropModeReplace 

Discards  the  previous  property  value  and  stores  the  new  data. 

•  PropModePrepend 

Inserts  the  data  before  the  beginning  of  the  existing  data.  If  the  property  is  undefined,  it 
is  treated  as  defined  with  the  correct  type  and  format  with  zero-length  data,  type  and 
format  arguments  must  match  the  existing  property  value;  otherwise  a  BadMatch 
error  occurs. 
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•  PropMode Append 

Appends  the  data  onto  the  end  of  the  existing  data.  If  the  property  is  undefined,  it  is 
treated  as  defined  with  the  correct  type  and  format  with  zero-length  data,  type  and 
format  arguments  must  match  the  existing  property  value;  otherwise  a  BadMatch 
error  occurs. 

The  property  may  remain  defined  even  after  the  client  which  defined  it  exits.  The  property 
becomes  undefined  only  if  the  application  calls  XDeleteProperty,  destroys  the  specified 
window,  or  closes  the  last  connection  to  the  X  server. 

The  maximum  size  of  a  property  is  server-dependent  and  can  vary  dynamically  if  the  server  has 
insufficient  memory. 

For  more  information,  see  Volume  One,  Chapter  10,  Interdient  Communication. 

Errors 

BadAlloc 

BadAtom 

BadMatch 

BadValue 

BadWindow 

Related  Commands 

XDeleteProperty, XGetAtomName,  XGetFontProperty,  XGetWindowProperty, 
XInternAtom,  XListProperties, XRotateWindowProperties, XSetStandard- 
Properties. 
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—  Xlib  -  Window  Save  Set- 


J  XChangeSaveSet 


Name 

XChangeSaveSet  —  add  or  remove  a  subwindow  from  the  client's  save-set. 

Synopsis 

XChangeSaveSet  { display,  w,  change_mode) 
Display  *display; 
Window  w; 
int  change_mode ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XGpenDisplay. 

w  Specifies  the  ID  of  the  window  whose  children  you  want  to  add  or  remove 

from  the  client's  save-set;  it  must  have  been  created  by  some  other  client. 

change_mode  Specifies  the  mode.  Pass  one  of  these  constants:  SetModelnsert  (adds 
the  window  to  this  client's  save-set)  or  SetModeDelete  (deletes  the  win 
dow  from  this  client's  save-set). 

Description 

XChangeSaveSet  adds  or  deletes  windows  from  a  client's  save-set.  This  client  is  usually 
the  window  manager. 

The  save-set  of  the  window  manager  is  a  list  of  other  client's  top-level  windows  which  have 
been  reparented.  If  the  window  manager  dies  unexpectedly,  these  top-level  application  win 
dows  are  children  of  a  window  manager  window  and  therefore  would  normally  be  destroyed. 
The  save-set  prevents  this  by  automatically  reparenting  the  windows  listed  in  the  save-set  to 
their  closest  existing  ancestor,  and  then  remapping  them. 

Windows  are  removed  automatically  from  the  save-set  by  the  server  when  they  are  destroyed. 

For  more  information  on  save-sets,  see  Volume  One,  Chapter  13,  Other  Programming  Tech 
niques. 

Errors 

BadMat  ch          w  not  created  by  some  other  client. 

BadValue 
BadWindow 

Related  Commands 

XAddToSaveSet,XRemoveFromSaveSet. 
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•Xlib  -  Window  Attributes- 


Name 

XChangeWindowAttributes  —  set  window  attributes. 

Synopsis 

XChangeWindowAttributes (display,  wf  valuemask,  attributes) 
Display  *display; 
Window  w; 

unsigned  long  valuemask; 
XSetWindowAttributes  *  attributes; 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID. 

valuemask  Specifies  which  window  attributes  are  defined  in  the  attributes  argu 
ment.  The  mask  is  made  by  combining  the  appropriate  mask  symbols  listed 
in  the  Structures  section  using  bitwise  OR  (|).  If  valuemask  is  zero,  the 
rest  is  ignored,  and  attributes  is  not  referenced.  The  values  and  restric 
tions  are  the  same  as  for  XCreateWindow. 

attributes  Window  attributes  to  be  changed.  The  valuemask  indicates  which  mem 
bers  in  this  structure  are  referenced. 

Description 

XChangeWindowAttributes  changes  any  or  all  of  the  window  attributes  that  can  be 
changed.  For  descriptions  of  the  window  attributes,  see  Volume  One,  Chapter  4,  Window  Attri 
butes. 

Changing  the  background  does  not  cause  the  window  contents  to  be  changed  immediately-not 
until  the  next  Expose  event  or  XClearWindow  call.  Drawing  into  the  pixmap  that  was  set 
as  the  background  pixmap  attribute  has  an  undefined  effect  on  the  window  background.  The 
server  may  or  may  not  make  a  copy  of  the  pixmap.  Setting  the  border  causes  the  border  to  be 
repainted  immediately.  Changing  the  background  of  a  root  window  to  None  or  Pa rent - 
Relative  restores  the  default  background  pixmap.  Changing  the  border  of  a  root  window  to 
CopyFromParent  restores  the  default  border  pixmap. 

Changing  the  win_gravity  does  not  affect  the  current  position  of  the  window.  Changing 
the  backing_store  of  an  obscured  window  to  WhenMapped  or  Always  may  have  no 
immediate  effect.  Also  changing  the  backing_jplanes,  backing_pixel,  or 
save_under  of  a  mapped  window  may  have  no  immediate  effect. 

Multiple  clients  can  select  input  on  the  same  window;  the  event_mask  attributes  passed  are 
disjoint.  When  an  event  is  generated  it  will  be  reported  to  all  interested  clients.  Therefore,  the 
setting  of  the  event_mask  attribute  by  one  client  will  not  affect  the  event_mask  of  others 
on  the  same  window.  However,  at  most,  one  client  at  a  time  can  select  each  of 
SubstructureRedirectMask,  ResizeRedirectMask,  and  ButtonPressMask  on 
any  one  window.  If  a  client  attempts  to  select  on  SubtructureRedirectMask,  Resize- 
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RedirectMask,  or  ButtonPressMask  and  some  other  client  has  already  selected  it  on  the 
same  window,  the  X  server  generates  a  BadAccess  error. 

There  is  only  one  do_not_propagate_mask  for  a  window,  not  one  per  client. 

Changing  the  colormap  attribute  of  a  window  generates  a  ColormapNotif  y  event.  Chang 
ing  the  colormap  attribute  of  a  visible  window  may  have  no  immediate  effect  on  the  screen 
(because  the  colormap  may  not  be  installed  until  the  window  manager  calls  Xlnstall- 
Colormap). 

Changing  the  cursor  of  a  root  window  to  None  restores  the  default  cursor. 

For  more  information,  see  Volume  One,  Chapter  2,  X  Concepts,  and  Chapter  4,  Window  Attri 
butes. 

Structures 

/* 

*  Data  structure  for  setting  window  attributes. 

*/ 
typedef  struct  { 

Pixmap  background_pixmap;  /*  pixmap.  None,  or  ParentRelative  */ 

unsigned  long  background_pixel;  /*  background  pixel  */ 

Pixmap  border_pixmap;  /*  pixmap,  None,  or  CopyFromParent  */ 

unsigned  long  border_pixel;  /*  border  pixel  value  */ 

int  bit_gravity;  /*  one  of  bit  gravity  values  */ 

int  win_gravity;  /*  one  of  the  window  gravity  values  */ 

int  backing_store;  /*  NotUseful,  WhenMapped,  Always  */ 

unsigned  long  backing_planes;  /*  planes  to  be  preseved  if  possible  */ 

unsigned  long  backing_pixel;  /*  value  to  use  in  restoring  planes  */ 

Bool  save_under;  /*  should  bits  under  be  saved  (popups)  */ 

long  event_mask;  /*  set  of  events  that  should  be  saved  */ 

long  do  not  propagate_mask;  /*  set  of  events  that  should  not  propagate  */ 

Bool  override_redirect;  /*  override  redirected  config  request  */ 

Colormap  colormap;  /*  colormap  to  be  associated  with  window  */ 

Cursor  cursor;  /*  cursor  to  be  displayed  (or  None)  */ 
}  XSetWindowAttributes; 

/*  Definitions  for  valuemask  argument  of  CreateWindow  and  ChangeWindowAttributes  */ 

#define  CWBackPixmap  (1L«0) 

#define  CWBackPixel  (1L«1) 

#define  CWBorderPixmap  (1L«2) 

#define  CWBorderPixel  (1L«3) 

#define  CWBitGravity  (1L«4) 

#define  CWWinGravity  (1L«5) 

#define  CWBackingStore  (1L«6) 

#define  CWBackingPlanes  (1L«7) 

#define  CWBackingPixel  (1L«8) 

#define  CWOverrideRedirect  (1L«9) 

#define  CWSaveUnder  (1L«10) 

#define  CWEventMask  (1L«11) 

#define  CWDontPropagate  (1L«12) 

fdefine  CWColormap  (1L«13) 

#define  CWCursor  (1L«14) 


Xlib  Reference  Manual  7S 


XChangeWindOW Attributes  (continued)  Xlib  -  Window  Attributes 

Errors 

BadAccess 

BadColormap 

BadCursor 

BadMatch 

BadPixmap 

BadValue 

BadWindow 


Related  Commands 

XGet Geometry,  XGetWindowAttributes, XSetWindowBackground,  XSet- 
WindowBackgroundPixmap, XSetWindowBorder,  XSetWindowBorderPixmap. 
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Name 

XChecklfEvent  —  check  the  event  queue  for  a  matching  event. 

Synopsis 

Bool  XChecklfEvent (display,  event,  predicate,  arg) 
Display  *display; 

XEvent  *  event;  /*  RETURN  */ 

Bool  (*predicate)  ()  ; 
char  *arg; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

event  Returns  the  matched  event. 

predicate       Specifies  the  procedure  that  is  called  to  determine  if  the  next  event  matches 
your  criteria. 

arg  Specifies  the  user- specified  argument  that  will  be  passed  to  the  predicate  pro 

cedure. 

Description 

XChecklfEvent  returns  the  next  event  in  the  queue  that  is  matched  by  the  specified  predi 
cate  procedure.  If  found,  that  event  is  removed  from  the  queue,  and  True  is  returned.  If  no 
match  is  found,  XChecklfEvent  returns  False  and  flushes  the  request  buffer.  No  other 
events  are  removed  from  the  queue.  Later  events  in  the  queue  are  not  searched. 

The  predicate  procedure  is  called  with  the  arguments  display,  event,  and  arg. 
For  more  information,  see  Volume  One,  Chapter  8,  Events. 

Related  Commands 

QLength,  XAllowEvents, XCheckMaskEvent, XCheckTypedEvent, XCheck- 
TypedWindowEvent, XCheckWindowEvent,  XEventsQueued,  XGetlnputFocus, 
XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent,  XPeekEvent,  XPeek- 
If Event, XPending, XPutBackEvent,XSelectInput,XSendEvent,XSet Input- 
Focus,  XSynchronize, XWindowEvent. 
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Name 

XCheckMaskEvent  —  remove  the  next  event  that  matches  mask;  don't  wait. 

Synopsis 

Bool  XCheckMaskEvent ( display,  event_mask,  event) 
Display  *  display; 
long  event_mask; 
XEvent  *  event;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

even t_mask     Specifies  the  event  types  to  be  returned.  See  list  under  XSelect  Input. 
event  Returns  a  copy  of  the  matched  event's  XEvent  structure. 

Description 

XCheckMaskEvent  removes  the  next  event  in  the  queue  that  matches  the  passed  mask.  The 
event  is  copied  into  an  XEvent  supplied  by  the  caller  and  XCheckMaskEvent  returns 
True.  Other  events  earlier  in  the  queue  are  not  discarded.  If  no  such  event  has  been  queued, 
XCheckMaskEvent  flushes  the  request  buffer  and  immediately  returns  False,  without  wait 
ing. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength,  XAllowEvents, XChecklf Event, XCheckTypedEvent, XCheckTyped- 
WindowEvent, XCheckWindowEvent, XEvent sQueued, XGetlnputFocus, XGet- 
MotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event, XPending,  XPutBackEvent, XSelectlnput,  XSendEvent,  XSetlnput- 
Focus, XSynchronize, XWindowEvent. 
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J  XCheckTypedEvent 


Name 

XCheckTypedEvent  —  return  the  next  event  in  queue  that  matches  event  type;  don't  wait. 

Synopsis 

Bool  XCheckTypedEvent (display,  event_type,  report) 
Display  *display; 
int  event_type ; 
XEvent  *  report;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDi splay. 

event_type     Specifies  the  event  type  to  be  compared. 
report  Returns  a  copy  of  the  matched  event  structure. 

Description 

XCheckTypedEvent  searches  first  the  event  queue,  then  the  events  available  on  the  server 
connection,  for  the  specified  even  t_ type.  If  there  is  a  match,  it  returns  the  associated  event 
structure.  Events  searched  but  not  matched  are  not  discarded.  XCheckTypedEvent  returns 
True  if  the  event  is  found.  If  the  event  is  not  found,  XCheckTypedEvent  flushes  the 
request  buffer  and  returns  False. 

This  command  is  similar  to  XCheckMaskEvent,  but  it  searches  through  the  queue  instead  of 
inspecting  only  the  last  item  on  the  queue.  It  also  matches  only  a  single  event  type  instead  of 
multiple  event  types  as  specified  by  a  mask. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength,  XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
WindowEvent, XCheckWindowEvent, XEventsQueued, XGetlnputFocus, XGet- 
MotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event,  XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus, XSynchronize, XWindowEvent. 
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x,ib- 


Name 

XCheckTypedWindowEvent  —  return  the  next  event  in  queue  matching  type  and  window. 

Synopsis 

Bool  XCheckTypedWindowEvent  (  display,  w,  event  _ty  pe  ,  report) 
Display  *  display; 
Window  w; 
int  event_type; 
XEvent  *  report;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID. 

even  t_  type     Specifies  the  event  type  to  be  compared. 

report  Returns  the  matched  event's  associated  structure  into  this  client-supplied 

structure. 

Description 

XCheckTypedWindowEvent  searches  first  the  event  queue,  then  any  events  available  on 
the  server  connection,  for  an  event  that  matches  the  specified  window  and  the  specified  event 
type.  Events  searched  but  not  matched  are  not  discarded. 

XCheckTypedWindowEvent  returns  True  if  the  event  is  found;  it  flushes  the  request  buffer 
and  returns  False  if  the  event  is  not  found. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength,  XAllowEvents,  XChecklf  Event,  XCheckMaskEvent,  XCheckTyped- 
Event,  XCheckWindowEvent,  XEventsQueued,  XGetlnputFocus,  XGetMotion- 
Events,  Xlf  Event,  XMaskEvent,  XNextEvent,  XPeekEvent,  XPeeklf  Event, 
XPending,  XPutBackEvent,  XSelectlnput,  XSendEvent,  XSetlnputFocus, 
XSynchronize,  XWindowEvent. 
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Name 

XCheckWindowEvent  —  remove  the  next  event  matching  both  passed  window  and  passed 
mask;  don't  wait. 

Synopsis 

Bool  XCheckWindowEvent (display,  w,  event_mask r  event) 
Display  *  display; 
Window  w; 
long  event_mask; 
XEvent  * event;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID.  The  event  must  match  both  the  passed  window  and 

the  passed  event  mask. 

even  t_mask     Specifies  the  event  mask.  See  XSelect  Input  for  a  list  of  mask  elements. 
event  Returns  the  XEvent  structure. 

Description 

XCheckWindowEvent  removes  the  next  event  in  the  queue  that  matches  both  the  passed 
window  and  the  passed  mask.  If  such  an  event  exists,  it  is  copied  into  an  XEvent  supplied  by 
the  caller.  Other  events  earlier  in  the  queue  are  not  discarded. 

If  a  matching  event  is  found,  XCheckWindowEvent  returns  True.  If  no  such  event  has  been 
queued,  it  flushes  the  request  buffer  and  returns  False,  without  waiting. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength, XAllowEvents, XChecklf Event,  XCheckMaskEvent,  XCheckTyped- 
Event,  XCheckTypedWindowEvent,  XEvent sQueued,  XGetlnputFocus,  XGet- 
MotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event,  XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus,  XSynchronize, XWindowEvent. 
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XCirculateSubwindows 

•Xlib  -  Window  Manipulation- 
Name 

XCirculateSubwindows  —  circulate  the  stacking  order  of  children  up  or  down. 

Synopsis 

XCirculateSubwindows ( display,  w,  direction) 
Display  *display; 
Window  w; 
int  direction; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID  of  the  parent  of  the  subwindows  to  be  circulated. 

direction        Specifies  the  direction  (up  or  down)  that  you  want  to  circulate  the  children. 
Pass  either  RaiseLowest  or  LowerHighest. 

Description 

XCirculateSubwindows  circulates  the  children  of  the  specified  window  in  the  specified 
direction,  either  RaiseLowest  or  LowerHighest.  If  some  other  client  has  selected 
SubstructureRedirectMask  on  the  specified  window,  then  a  CirculateRequest 
event  is  generated,  and  no  further  processing  is  performed.  If  you  specify  RaiseLowest,  this 
function  raises  the  lowest  mapped  child  (if  any)  that  is  occluded  by  another  child  to  the  top  of 
the  stack.  If  you  specify  LowerHighest,  this  function  lowers  the  highest  mapped  child  (if 
any)  that  occludes  another  child  to  the  bottom  of  the  stack.  Exposure  processing  is  performed 
on  formerly  obscured  windows. 

For  more  information,  see  Volume  One,  Chapter  14,  Window  Management. 

Errors 

BadValue 
BadWindow 

Related  Commands 

XCirculateSubwindowsDown, XCirculateSubwindowsUp,  XConf igureWindow, 
XLowerWindow,  XMoveResizeWindow, XMoveWindow, XQueryTree,  XRaise- 
Window,  XReparentWindow, XResizeWindow,  XRestackWindows. 
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-x..b-w,ndowMan.pu.at,on '          XCirculateSubwindowsDown 

Name 

XCirculateSubwindowsDown  —  circulate  the  bottom  child  to  the  top  of  the  stacking  order. 

Synopsis 

XCirculateSubwindowsDown (display,    w) 
Display    * display ; 
Window   w; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID  of  the  parent  of  the  windows  to  be  circulated. 

Description 

XCirculateSubwindowsDown  lowers  the  highest  mapped  child  of  the  specified  window 
that  partially  or  completely  obscures  another  child.  The  lowered  child  goes  to  the  bottom  of  the 
stack.  Completely  unobscured  children  are  not  affected. 

This  function  generates  exposure  events  on  any  window  formerly  obscured.  Repeated  execu 
tions  lead  to  round-robin  lowering.  This  is  equivalent  to  XCirculateSubwindows  (dis 
play,  w,  LowerHighest). 

If  some  other  client  has  selected  SubstructureRedirectMask  on  the  window,  then  a 
CirculateRequest  event  is  generated,  and  no  further  processing  is  performed.  This  allows 
the  window  manager  to  intercept  this  request  when  w  is  the  root  window.  Usually,  only  the 
window  manager  will  call  this  on  the  root  window. 

For  more  information,  see  Volume  One,  Chapter  14,  Window  Management. 

Errors 

BadWindow 

Related  Commands 

XCirculateSubwindows, XCirculateSubwindowsUp, XConf igureWindow, 
XLowerWindow, XMoveResizeWindow, XMoveWindow, XQueryTree, XRaise- 
Window,  XReparentWindow, XResizeWindow,  XRestackWindows. 
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XCirculateSubwindowsUp  , vn 

v Xlib  -  Window  Manipulation  — 

Name 

XCirculateSubwindowsUp  —  circulate  the  top  child  to  the  bottom  of  the  stacking  order. 

Synopsis 

XCirculateSubwindowsUp  (display,    w) 
Display    * display ; 
Window   w; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID  of  the  parent  of  the  windows  to  be  circulated. 

Description 

XCirculateSubwindowsUp  raises  the  lowest  mapped  child  of  the  specified  window  that  is 
partially  or  completely  obscured  by  another  child.  The  raised  child  goes  to  the  top  of  the  stack. 
Completely  unobscured  children  are  not  affected.  This  generates  exposure  events  on  the  raised 
child  (and  its  descendents,  if  any).  Repeated  executions  lead  to  round  robin-raising.  This  is 
equivalent  to  XCirculateSubwindows  (display,  w,  RaiseLowest). 

If  some  other  client  has  selected  SubstructureRedirectMask  on  the  window,  then  a 
CirculateRequest  event  is  generated,  and  no  further  processing  is  performed.  This  allows 
the  window  manager  to  intercept  this  request  when  w  is  the  root  window.  Usually,  only  the 
window  manager  will  call  this  on  the  root  window. 

For  more  information,  see  Volume  One,  Chapter  14,  Window  Management. 

Errors 

BadWindow 

Related  Commands 

XCirculateSubwindows,  XCirculateSubwindowsDown,  XConf igureWindow, 
XLowerWindow,  XMoveResizeWindow, XMoveWindow, XQueryTree,  XRaise- 
Window,  XReparentWindow, XResizeWindow,  XRestackWindows. 
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— Xllb  -  Drawing  Primitives ' 

Name 

XClearArea  —  clear  a  rectangular  area  in  a  window. 
Synopsis 

XClearArea (display,  w,  x,  y,  width,  height,  exposures) 
Display  *display; 
Window  w; 
int  xf  y; 

unsigned  int  width,  height; 
Bool  exposures; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  an  input  Output  window. 

x  Specify  the  x  and  y  coordinates  of  the  upper-left  corner  of  the  rectangle  to  be 

y  cleared,  relative  to  the  origin  of  the  window. 

wi  dth  Specify  the  dimensions  in  pixels  of  the  rectangle  to  be  cleared. 

height 

exposures    Specifies  whether  exposure  events  are  generated.    Must  be  either  True  or 
False. 

Description 

XClearArea  clears  a  rectangular  area  in  a  window. 

If  width  is  zero,  the  window  is  cleared  from  x  to  the  right  edge  of  the  window.  If  height  is 
zero,  the  window  is  cleared  from  y  to  the  bottom  of  the  window.  See  figure  above.. 

If  the  window  has  a  defined  background  tile  or  it  is  ParentRelative,  the  rectangle  is  tiled 
with  a  plane_mask  of  all  1's,  a  function  of  GXcopy,  and  a  subwindow_mode  of 
ClipByChildren.  If  the  window  has  background  None,  the  contents  of  the  window  are  not 
changed.  In  either  case,  if  exposures  is  True,  then  one  or  more  exposure  events  are  gen 
erated  for  regions  of  the  rectangle  that  are  either  visible  or  are  being  retained  in  a  backing  store. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
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(continued) 
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Window 


[x,y]       width 


Window 


[x,y]       width 


Window 


[x,y]  width   =   0 


Window 


[x,y]  width  =  0 


Errors 

BadMatch 
BadValue 
BadWindow 


Window  is  an  inputOnly  class  window. 


Related  Commands 

XClearWindow,  XCopyArea,  XCopyPlane,  XDraw,  XDrawArc,  XDrawArcs,  XDraw- 
Filled,  XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDrawRectangle, 
XDrawRectangles, XDrawSegments, XFillArc, XFillArcs,  XFillPolygon, 
XFillRectangle, XFillRectangles. 
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Name 

XClearWindow  —  clear  an  entire  window. 

Synopsis 

XClearWindow (display,  w) 
Display  *display; 
Window  W, 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDi splay. 

w  Specifies  the  ID  of  the  window  to  be  cleared. 

Description 

XClearWindow  clears  a  window,  but  does  not  cause  exposure  events.  This  function  is  equiv 
alent  to  XClearArea  (display,  w,  0,  0,  0,  0,  False). 

If  the  window  has  a  defined  background  tile  or  it  is  ParentRelative,  the  rectangle  is  tiled 
with  a  plane_mask  of  all  1's  and  function  of  GXcopy.  If  the  window  has  background 
None,  the  contents  of  the  window  are  not  changed. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Errors 

BadMatch          If  vis  an  InputOnly  class  window. 

BadValue 
BadWindow 

Related  Commands 

XClearArea, XCopyArea, XCopyPlane, XDraw,  XDrawArc,  XDrawArcs,  XDraw- 
Filled, XDrawLine, XDrawLines, XDrawPoint,  XDrawPoints,  XDrawRectangle, 
XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFillPolygon, 
XFillRectangle, XFillRectangles. 


Xlib  Reference  Manual  87 


XCIipBox  ~\ 

X Xlib  -  Regions- 
Name 

XCIipBox  —  generate  the  smallest  rectangle  enclosing  a  region. 

Synopsis 

XCIipBox  (r,  rect) 
Region  r; 
XRect angle  *rect ;          /*  RETURN  */ 

Arguments 

r  Specifies  the  region. 

rect  Returns  the  smallest  rectangle  enclosing  region  r. 

Description 

XCIipBox  returns  the  smallest  rectangle  that  encloses  the  given  region. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion,  XPolygonRegion, 
XRect InRegion, XSetRegion, XShrinkRegion,  XSubtractRegion, XUnion- 
RectWithRegion, XUnionRegion,  XXorRegion. 
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J  XCIoseDisplay 


Name 

XCIoseDisplay  —  disconnect  a  client  program  from  an  X  server  and  display. 

Synopsis 

XCIoseDisplay (display) 
Display   *display; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

Description 

XCIoseDisplay  closes  the  connection  between  the  current  client  and  the  X  server  specified 
by  the  Display  argument. 

The  XCIoseDisplay  routine  destroys  all  windows,  resource  IDs  (Window,  Font,  Pixmap, 
Colormap,  Cursor,  and  GContext),  or  other  resources  (GCs)  that  the  client  application 
has  created  on  this  display,  unless  the  close  down  mode  of  the  client's  resources  has  been 
changed  by  XSetCloseDownMode.  Therefore,  these  windows,  resource  IDs,  and  other 
resources  should  not  be  referenced  again.  In  addition,  this  routine  discards  any  requests  that 
have  been  buffered  but  not  yet  sent  to  the  server. 

Although  these  operations  automatically  (implicitly)  occur  when  a  process  exits  under  UNIX, 
you  should  call  XCIoseDisplay  anyway. 

For  more  information,  see  Volume  One,  Chapter  3,  Basic  Window  Program. 
Related  Commands 

Def  aultScreen,  XFree,  XNoOp,  XOpenDisplay. 
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XConfigureWindow  . V| 

v Xlib  -  Window  Manipulation  — 

Name 

XConfigureWindow  —  change  the  window  position,  size,  border  width,  or  stacking  order. 

Synopsis 

XConf  igureWindow  (  display,  i/,  value_mask ,  values) 
Display  * display; 
Window  w; 

unsigned  int  value_mask; 
XWindowChanges  * values; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  to  be  reconfigured. 

value_mask  Specifies  which  values  are  to  be  set  using  information  in  the  values  struc 
ture,  val  ue_mask  is  the  bitwise  OR  of  any  number  of  symbols  listed  in  the 
Structures  section  below. 

val  ues  Specifies  a  pointer  to  the  XWindowChanges  structure  containing  new  confi 

guration  information.  See  the  Structures  section  below. 

Description 

XConfigureWindow  changes  the  window  position,  size,  border  width,  and/or  the  stacking 
order.  If  selected,  a  Conf  igureNot  if  y  event  is  generated  to  announce  any  changes. 

If  the  window  to  be  reconfigured  is  a  top-level  window,  there  will  be  interaction  with  the  win 
dow  manager  if  the  override_redirect  attribute  of  the  window  is  False.  In  this  case, 
the  X  server  sends  a  Conf  igureRequest  event  to  the  window  manager  and  does  not  recon 
figure  the  window.  The  window  manager  receives  this  event  and  then  makes  the  decision 
whether  to  allow  the  application  to  reconfigure  its  window.  The  client  should  wait  for  the 
Conf  igureNot  if  y  event  to  find  out  the  size  and  position  of  the  window. 

In  Release  4,  XReconf  igureWMWindow  should  be  used  instead  of  XConfigureWindow 
for  top-level  windows.  This  routine  handles  restacking  of  top-level  windows  properly. 

If  a  window's  size  actually  changes,  the  window's  subwindows  may  move  according  to  their 
window  gravity.  If  they  do,  GravityNotif  y  events  will  be  generated  for  them.  Depending 
on  the  window's  bit  gravity,  the  contents  of  the  window  also  may  be  moved.  See  Volume  One, 
Chapter  4,  Window  Attributes  for  further  information. 

Exposure  processing  is  performed  on  formerly  obscured  windows,  including  the  window  itself 
and  its  inferiors,  if  regions  of  them  were  obscured  but  afterward  are  not.  As  a  result  of  increas 
ing  the  width  or  height,  exposure  processing  is  also  performed  on  any  new  regions  of  the  win 
dow  and  any  regions  where  window  contents  are  lost. 

The  members  of  XWindowChanges  that  you  specify  in  val  ues  are: 
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Xlib  -  Window  Manipulation 


(continued) 


XConfigureWindow 


x  Specify  the  x  and  y  coordinates  of  the  upper-left  outer  comer  of  the  window 

y  relative  to  the  parent's  origin. 

width  Specify  the  inside  size  of  the  window  in  pixels,  not  including  the  border. 

height  These  arguments  must  be  positive. 

horde  r_width 

Specifies  the  width  of  the  border  in  pixels. 

sibling  Specifies  the  sibling  window  for  stacking  operations.   If  not  specified,  no 

change  in  the  stacking  order  will  be  made.  If  specified,  stack_mode  must 
also  be  specified. 

stack_mode     The  stack  mode  can  be  any  of  these  constants:    Above,  Below,  Toplf , 
Bottomlf ,  or  Opposite. 

The  computation  for  the  Bottomlf,  Toplf,  and  Opposite  stacking  modes  is  performed 
with  respect  to  window  i/s  final  size  and  position  (as  controlled  by  the  other  arguments  to 
XConfigureWindow,  not  its  initial  position.)  It  is  an  error  if  sibling  is  specified  without 
stack_mode.  If  sibling  and  stack_mode  are  specified,  the  window  is  restacked  as  fol 
lows: 

Stacking  Flag      Position 


Above 
Below 
Toplf 

Bottomlf 
Opposite 


w  is  placed  just  above  sibling 
w  is  placed  just  below  sibling 

if  sibling  obscures  w,  then  w  is  placed  at  the  top 
of  the  stack 

if  w  obscures  sibling,  then  w  is  placed  at  the  bot 
tom  of  the  stack 

if  sibling  occludes  v/,  then  w  is  placed  at  the  top 
of  the  stack.  If  w  occludes  sibling,  then  w  is 
placed  at  the  bottom  of  the  stack.  If  wand  sibling 
do  not  overlap,  no  change  is  made. 
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XConfigureWindOW  (continued)  Xlib  -  Window  Manipulation 

If  a  stack_mode  is  specified  but  no  sibling  is  specified,  the  window  is  restocked  as  follows: 


Stacking  Flag 


Above 
Below 
Toplf 

Bottomlf 
Opposite 


Position 


w  is  placed  at  the  top  of  the  stack 
w  is  placed  at  the  bottom  of  the  stack 

if  any  sibling  obscures  w,  then  w  is  placed  at  the  top 
of  the  stack 

if  w  obscures  any  sibling,  then  window  is  placed  at 
the  bottom  of  the  stack 

if  any  sibling  occludes  w,  then  w  is  placed  at  the  top 
of  the  stack,  else  if  w  occludes  any  sibling,  then  w  is 
placed  at  the  bottom  of  the  stack 


Under  Release  4,  use  XReconf  igureWMWindow  to  configure  a  top-level  window. 
Structures 

typedef   struct    { 

int   x,    y; 

int  width,  height; 

int  border_width; 

Window  sibling; 

int  stack_mode; 
}  XWindowChanges; 

/*  Conf igureWindow  structure  */ 

/*  ChangeWindow  value  bits  definitions  for  valuemask  */ 

tdefine  CWX  (1«0) 

#define  CWY  (1«1) 

#define  CWWidth  (1«2) 

tdefine  CWHeight  (1«3) 

#define  CWBorderWidth       (1«4) 

#define  CWSibling  (1«5) 

#define  CWStackMode         (1«6) 


Errors 

BadMatch 


Attempt  to  set  any  invalid  attribute  of  InputOnly  window. 
sibling  specified  without  a  stack_mode. 
The  sibling  window  is  not  actually  a  sibling. 


BadValue     width  or  height  isO. 
BadWindow 
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Xlib  -  Window  Manipulation  (continued)  XConf  IgureWlndOW 

Related  Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp,  XLowerWindow,  XMoveResizeWindow,  XMoveWindow,  XQuery- 
Tree,  XReconf  igureWMWindow,  XRaiseWindow,  XReparentWindow,  XResize- 
Window, XRestackWindows. 
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XConvertSelection  A 


Name 

XConvertSelection  —  use  the  value  of  a  selection. 

Synopsis 

XConvertSelection ( display,  selection,  target,  property, 

requestor,  time) 
Display  *  display; 
Atom  selection,  target; 

Atom  property;  /*  may  be  None  */ 

Window  requestor; 
Time  time; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

selection  Specifies  the  selection  atom.  XA_PRIMARY  and  XA_SECONDARY  are  the  stan 
dard  selection  atoms. 

target  Specifies  the  atom  of  the  type  property  that  specifies  the  desired  format  for 

the  data. 

property  Specifies  the  property  in  which  the  requested  data  is  to  be  placed.  None  is 
also  valid,  but  current  conventions  specify  that  the  requestor  is  in  a  better 
position  to  select  a  property  than  the  selection  owner. 

requestor       Specifies  the  requesting  window. 

time  Specifies  the  time  when  the  conversion  should  take  place.    Pass  either  a 

timestamp,  expressed  in  milliseconds,  or  the  constant  CurrentTime. 

Description 

XConvertSelection  causes  a  SelectionRequest  event  to  be  sent  to  the  current  selec 
tion  owner  if  there  is  one,  specifying  the  property  to  store  the  data  in  (selection),  the  format 
to  convert  that  data  into  before  storing  it  (target),  the  property  to  place  the  information  in 
(property),  the  window  that  wants  the  information  (requestor),  and  the  time  to  make  the 
conversion  (time). 

The  selection  owner  responds  by  sending  a  SelectionNotify  event,  which  confirms  the 
selected  atom  and  type.  If  no  owner  for  the  specified  selection  exists,  or  if  the  owner  could  not 
convert  to  the  type  specified  by  requestor,  the  X  server  generates  or  the  owner  sends  a 
SelectionNotify  event  to  the  requestor  with  property  None.  Whether  or  not  the  owner 
exists,  the  arguments  are  passed  unchanged.  See  Volume  One,  Chapter  I0,lnterclient  Commu 
nication,  for  a  description  of  selection  events  and  selection  conventions. 

Errors 

BadAtom 
BadWindow 

Related  Commands 

XGet Select ionOwner, XSetSelectionOwner. 
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—  Xlib  -  Drawing  Primitives- 


J  XCopyArea 


Name 

XCopyArea  —  copy  an  area  of  a  drawable. 

Synopsis 

XCopyArea (display,  src,  dest ,  gc ,  src_x,  src_y,  width, 

height,   dest_x,  dest_y) 
Display  *display; 
Drawable  src,  dest; 
GC  gc; 

int  src_x,  src_y; 
unsigned  int  width,  height; 
int  dest_x,  dest_y ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

src  Specify  the  source  and  destination  rectangles  to  be  combined,    src  and 

dest  dest  must  have  the  same  root  and  depth. 

gc  Specifies  the  graphics  context. 

src_x  Specify  the  x  and  y  coordinates  of  the  upper- left  corner  of  the  source  rectan- 

src_y  gle  relative  to  the  origin  of  the  source  drawable. 

width  Specify  the  dimensions  in  pixels  of  both  the  source  and  destination  rectan- 

height  gles. 

dest_x  Specify  the  x  and  y  coordinates  within  the  destination  window. 

dest_y 

Description 

XCopyArea  combines  the  specified  rectangle  of  src  with  the  specified  rectangle  of  dest. 
src  and  dest  must  have  the  same  root  and  depth. 

If  regions  of  the  source  rectangle  are  obscured  and  have  not  been  retained  in  back- 
ing_store,  or  if  regions  outside  the  boundaries  of  the  source  drawable  are  specified,  then 
those  regions  are  not  copied.  Instead,  the  following  occurs  on  all  corresponding  destination 
regions  that  are  either  visible  or  are  retained  in  backing_store.  If  dest  is  a  window  with 
a  background  other  than  None,  the  corresponding  regions  of  the  destination  are  tiled  (with 
plane_mask  of  all  1's  and  function  GXcopy)  with  that  background.  Regardless  of  tiling,  if 
the  destination  is  a  window  and  graphics_exposures  in  gc  is  True,  then  Graphics - 
Expose  events  for  all  corresponding  destination  regions  are  generated.  If  graph- 
ics_exposures  is  True  but  no  regions  are  exposed,  then  a  NoExpose  event  is  generated. 

If  regions  of  the  source  rectangle  are  not  obscured  and  graphics_exposures  is  False, 
one  NoExpose  event  is  generated  on  the  destination. 
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XCopyArea  uses  these  graphics  context  components:   function,  plane_mask, 
subwindow_mode,  graphics_exposures,  clip_x_origin,  clip_y_origin,  and 
clip_mask. 

Errors 

BadDrawable 

BadGC 

BadMatch  The  src  and  dest  rectangles  do  not  have  the  same  root  and  depth. 

Related  Commands 

XClearArea,  XClearWindow,  XCopyPlane,  XDraw,  XDrawArc,  XDrawArcs, 
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw- 
Rectangle,  XDrawRectangles, XDrawSegments, XFillArc,  XFillArcs,  XFill- 
Polygon, XFillRectangle, XFillRectangles. 
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— Xlib-Colormaps- 


j  XCopyColormapAndFree 


Name 

XCopyColormapAndFree  —  copy  a  colormap  and  return  a  new  colormap  ID. 

Synopsis 

Colormap  XCopyColormapAndFree ( display f  cmap) 
Display  *display; 
Colormap  cmap; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

cmap  Specifies  the  colormap  you  are  moving  out  of. 

Description 

XCopyColormapAndFree  is  used  to  obtain  a  new  virtual  colormap  when  allocating  color- 
cells  out  of  a  previous  colormap  has  failed  due  to  resource  exhaustion  (that  is,  too  many  cells  or 
planes  were  in  use  in  the  original  colormap). 

XCopyColormapAndFree  moves  all  of  the  client's  existing  allocations  from  cmap  to  the 
returned  Colormap  and  frees  those  entries  in  cmap.  The  visual  type  and  screen  for  the  new 
colormap  is  the  same  as  for  the  old. 

If  cmap  was  created  by  the  client  with  the  all oc  argument  set  to  All oc All,  the  new  color- 
map  is  also  created  with  AllocAll,  all  color  values  for  all  entries  are  copied  from  cmap,  and 
then  all  entries  in  cmap  are  freed. 

If  cmap  was  created  by  the  client  with  AllocNone,  the  allocations  to  be  moved  are  all  those 
pixels  and  planes  that  have  been  allocated  by  the  client  using  XAllocColor,  XAlloc- 
NamedColor,  XAllocColorCells,  or  XAllocColorPlanes  and  that  have  not  been 
freed  since  they  were  allocated.  Values  in  other  entries  of  the  new  Colormap  are  undefined. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 

Errors 

BadAlloc 
BadColormap 

Related  Commands 

Def aultColormap,  DisplayCells, XCreateColormap,  XFreeColormap,  XGet- 
StandardColormap, XInstallColormap,  XListlnstalledColormaps, XSet- 
StandardColormap, XSetWindowColormap,  XUninstallColormap. 
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Name 

XCopyGC  —  copy  a  graphics  context. 

Synopsis 

XCopyGC  (display,  src,  valuemask ,  dest) 
Display  *display; 
GC  src,  dest; 
unsigned  long  valuemask; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

src  Specifies  the  components  of  the  source  graphics  context. 

valuemask  Specifies  the  components  in  the  source  GC  structure  to  be  copied  into  the  des 
tination  GC.  valuemask  is  made  by  combining  any  number  of  the  mask 
symbols  listed  in  the  Structures  section  using  bitwise  OR  (|). 

dest  Specifies  the  destination  graphics  context. 

Description 

XCopyGC  copies  the  selected  elements  of  one  graphics  context  to  another.  See  Volume  One, 
Chapter  5,  The  Graphics  Context,  for  a  description  of  the  graphics  context. 

Structures 

The  GC  structure  contains  the  following  elements: 

/* 

*  Data  structure  for  setting  graphics  context. 

*/ 
typedef  struct  { 

int  function;  /*  logical  operation  */ 

unsigned  long  plane_mask;  /*  plane  mask  */ 

unsigned  long  foreground;  /*  foreground  pixel  */ 

unsigned  long  background;  /*  background  pixel  */ 

int  line_width;  /*  line  width  */ 

int  line_style;  /*  Solid,  OnOffDash,  DoubleDash  */ 

int  cap_style;  /*  NotLast,  Butt,  Round,  Projecting  */ 

int  join_style;  /*  Miter,  Round,  Bevel  */ 

int  fill_style;  /*  Solid,  Tiled,  Stippled  */ 

int  fill_rule;  /*  EvenOdd,  Winding  */ 

int  arc_mode;  /*  PieSlice  */ 

Pixmap  tile;  /*  tile  pixmap  for  tiling  operations  */ 

Pixmap  stipple;  /*  stipple  1  plane  pixmap  for  stipping  */ 

int  ts_x_origin;  /*  offset  for  tile  or  stipple  operations  */ 

int  ts_y_origin; 

Font  font;  /*  default  text  font  for  text  operations  */ 

int  subwindow_mode;  /*  ClipByChildren,  Includelnf eriors  */ 

Bool  graphics_exposures;  /*  boolean,  should  exposures  be  generated  */ 

int  clip_x_origin;  /*  origin  for  clipping  */ 
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int  clip_y_origin; 

Pixmap  clip_mask;          /*  bitmap  clipping;  other  calls  for  rects  */ 
int  dash_offset;  /*  patterned/dashed  line  information  */ 

char  dashes; 
}  XGCValues; 


#define  GCFunction 

#define  GCPlaneMask 

tdefine  GCForeground 

#define  GCBackground 

#define  GCLineWidth 

#define  GCLineStyle 

#define  GCCapStyle 

tdefine  GCJoinStyle 

tdefine  GCFillStyle 

tdefine  GCFillRule 

#define  GCTile 

#define  GCStipple 

#define  GCTileStipXOrigin 

tdefine  GCTileStipYOrigin 

tdefine  GCFont 

tdefine  GCSubwindowMode 

tdefine  GCGraphicsExposures 

tdefine  GCClipXOrigin 

tdefine  GCClipYOrigin 

tdefine  GCClipMask 

tdefine  GCDashOffset          (1L«20) 

tdefine  GCDashList  (1L«21) 

tdefine  GCArcMode  (1L«22) 

Errors 

BadAlloc 

BadGC 

BadMatch          src  and  dest  do  not  have  the  same  root  and  depth. 

Related  Commands 

Def  aultGC,  XChangeGC,  XCreateGC,  XFreeGC,  XGContextFromGC,  XGet- 
GCValues,  XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, 
XSetClipRectangles, XSetDashes, XSetFillRule,  XSetFillStyle, XSet- 
Foreground, XSetFunction, XSetGraphicsExposures, XSetLineAttributes, 
XSetPlaneMask, XSetState, XSetStipple, XSetSubwindowMode, XSet- 
TSOrigin. 
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XCopyPlane  \ xnb  _  Drawlng 

Name 

XCopyPlane  —  copy  a  single  plane  of  a  drawable  into  a  drawable  with  depth,  applying  pixel 
values. 

Synopsis 

XCopyPlane ( display,  src,  dest ,  gc ,  src_xr  src_yr  width, 

height,  dest_x ,  dest_y,  plane) 
Display  *display; 
Drawable  src,  dest', 
GC  gc; 

int  src_x,  src_y; 
unsigned  int  width,  height; 
int  dest_x,  dest_y; 
unsigned  long  plane; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

src  Specify  the  source  and  destination  drawables. 

dest 

gc  Specifies  the  graphics  context. 

src_x  Specify  the  x  and  y  coordinates  of  the  upper-left  corner  of  the  source  rectan- 

src_y  gle  relative  to  the  origin  of  the  drawable. 

width  Specify  the  width  and  height  in  pixels.  These  are  the  dimensions  of  both  the 

height  source  and  destination  rectangles. 

dest_x  Specify  the  x  and  y  coordinates  at  which  the  copied  area  will  be  placed  rela- 

dest_y  live  to  the  origin  of  the  destination  drawable. 

plane  Specifies  the  source  bit-plane.  You  must  set  exactly  one  bit,  and  the  bit  must 

specify  a  plane  that  exists  in  src. 

Description 

XCopyPlane  copies  a  single  plane  of  a  rectangle  in  the  source  into  the  entire  depth  of  a  corre 
sponding  rectangle  in  the  destination.  The  plane  of  the  source  drawable  and  the  f  ore- 
ground/background  pixel  values  in  gc  are  combined  to  form  a  pixmap  of  the  same  depth 
as  the  destination  drawable,  and  the  equivalent  of  an  XGopyArea  is  performed,  with  all  the 
same  exposure  semantics. 

XCopyPlane  uses  these  graphics  context  components:  function,  plane_mask, 
foreground, background,  subwindow_mode,  graphics_exposures, 
clip_x_origin,  clip_y_origin,  and  clip_mask. 

The  src  and  dest  drawables  must  have  the  same  root,  but  need  not  have  the  same  depth. 
For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
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Errors 

BadDrawable 

BadGC 

BadMatch          src  and  dest  do  not  have  the  same  root 

BadValue          plane  does  not  have  exactly  one  bit  set,  or  bit  specified  in  plane  is  not  a 
plane  in  src. 

Related  Commands 

XClearArea,  XClearWindow,  XCopyArea,  XDraw,  XDrawArc,  XDrawArcs,  XDraw- 
Filled,  XDrawLine, XDrawLines,  XDrawPoint,  XDrawPoints,  XDrawRectangle, 
XDrawRectangles, XDrawSegments, XFillArc,  XFillArcs,  XFillPolygon, 
XFillRectangle, XFillRectangles. 
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XCreateAssocTable 

Xlib  -  Association  Tables— 

Name 

XCreateAssocTable  —  create  a  new  association  table  (X10). 

Synopsis 

XAssocTable  *XCreateAssocTable (size) 
int  size; 

Arguments 

si  ze  Specifies  the  number  of  buckets  in  the  hashed  association  table. 

Description 

XCreateAssocTable  creates  an  association  table,  which  allows  you  to  associate  your  own 
structures  with  X  resources  in  a  fast  lookup  table.  This  function  is  provided  for  compatibility 
with  X  Version  10.  To  use  it  you  must  include  the  file  <Xll/X10.h>  and  link  with  the  library 
-loldX. 

The  size  argument  specifies  the  number  of  buckets  in  the  hash  system  of  XAssocTable. 
For  reasons  of  efficiency  the  number  of  buckets  should  be  a  power  of  two.  Some  size  sugges 
tions  might  be:  use  32  buckets  per  100  objects;  a  reasonable  maximum  number  of  object  per 
buckets  is  8. 

If  there  is  an  error  allocating  memory  for  the  XAssocTable,  a  NULL  pointer  is  returned. 
For  more  information  on  association  tables,  see  Volume  One,  Appendix  E,X10  Compatibility. 

Structures 

typedef  struct  { 

XAssoc  *buckets;        /*  pointer  to  first  bucket  in  array  */ 
int  size;  /*  table  size  (number  of  buckets)  */ 

}  XAssocTable; 

Related  Commands 

XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc,  XMakeAssoc. 
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—  Xlib  -  Pixmaps  and  Tiles- 


J  XCreateBitmapFromData 


Name 

XCreateBitmapFromData  —  create  a  bitmap  from  xil  bitmap  format  data. 

Synopsis 

Pixmap  XCreateBitmapFromData ( display,  drawable,  data, 

width,  height) 
Display  *display; 
Drawable  drawable; 
char  *data; 
unsigned  int  width,  height; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

drawable          Specifies  a  drawable.  This  determines  which  screen  to  create  the  bitmap  on. 
data  Specifies  the  bitmap  data,  in  XI 1  bitmap  file  format. 

width  Specify  the  dimensions  in  pixels  of  the  created  bitmap.  If  smaller  than  the 

height  bitmap  data,  the  upper-left  corner  of  the  data  is  used. 

Description 

XCreateBitmapFromData  creates  a  single-plane  pixmap  from  an  array  of  hexadecimal 
data.  This  data  may  be  defined  in  the  program  or  included.  The  bitmap  data  must  be  in  X  ver 
sion  11  format  as  shown  below  (it  cannot  be  in  X10  format).  The  following  format  is  assumed 
for  the  data,  where  the  variables  are  members  of  the  ximage  structure  described  in  Volume 
One,  Chapter  6,  Drawing  Graphics  and  Text: 

f ormat=XYP  ixmap 

bit_order=LSBFirst 

byte_order=LSBFirst 

bitmap_unit=8 

bitmap_pad=8 

xof fset=0 

no  extra  bytes  per  line 

XCreateBitmapFromData  creates  an  image  with  the  specified  data  and  copies  it  into  the 
created  pixmap.  The  following  is  an  example  of  creating  a  bitmap: 

tdefine  gray__width  16 

tdefine  gray_height  16 

tdefine  gray_x_hot  8 

tdefine  gray_y_hot  8 

static  char  gray_bits []  =  { 

Oxf8,  Oxlf,  Oxe3,  Oxc7,  Oxcf,  Oxf3,  Ox9f,  Oxf9, 
Oxbf,  Oxfd,  0x33,  Oxcc,  Oxlf,  Oxfe,  Oxlf,  Oxfe, 
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Ox7e,    Ox7e,    Ox7f,    Oxfe,    0x37,    Oxec,    Oxbb,    Oxdd, 
Ox9c,    0x39,    Oxcf,    Oxf3,    Oxe3,    Oxc7,    Oxf8,    Oxlf}; 

Pixmap   XCreateBitmapFromData (display,    window,    gray_bits, 
gray_width,    gray_height) ; 

If  the  call  could  not  create  a  pixmap  of  the  requested  size  on  the  server,  XCreateBitmap 
FromData  returns  0  (zero),  and  the  server  generates  a  BadAlloc  error.  If  the  requested 
depth  is  not  supported  on  the  screen  of  the  specified  drawable,  the  server  generates  a  Bad- 
Match  error. 

The  user  should  free  the  bitmap  using  XFreePixmap  when  it  is  no  longer  needed. 
For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Errors 

BadAlloc          Server  has  insufficient  memory  to  create  bitmap. 

BadDrawable 

BadValue    Specified  bitmap  dimensions  are  zero. 
Related  Commands 

XCreatePixmap, XCreatePixmapFromBitmapData, XCreatePixmapFrom- 
BitmapData, XFreePixmap, XQueryBestSize,  XQueryBestStipple, XQuery- 
BestTile, XReadBitmapFile, XSetTile,  XSetWindowBackgroundPixmap, 
XSetWindowBorderPixmap, XWriteBitmapFile. 
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—  Xlib  -  Colormaps - 


J  XCreateColormap 


Name 

XCreateColormap  —  create  a  colormap. 

Synopsis 

Colormap   XCreateColormap ( display,    w,    visual,    alloc) 
Display    *display; 
Window   w; 
Visual    *visual; 
int    alloc; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  a  window  ID.  The  colormap  created  will  be  associated  with  the 

same  screen  as  the  window. 

visual  Specifies  a  pointer  to  the  visual  structure  for  the  colormap.   The  visual 

class  and  depth  must  be  supported  by  the  screen. 

alloc  Specifies  how  many  colormap  entries  to  allocate.  Pass  either  AllocNone  or 

AllocAll. 

Description 

XCreateColormap  creates  a  colormap  of  the  specified  visual  type  and  allocates  either  none 
or  all  of  its  entries,  and  returns  the  colormap  ID. 

It  is  legal  to  specify  any  visual  class  in  the  structure  pointed  to  by  the  visual  argument.  If  the 
class  is  StaticColor,  StaticGray,  or  TrueColor,  the  colorcells  will  have  pre-allocated 
read-only  values  defined  by  the  individual  server  but  unspecified  by  the  XI 1  protocol.  In  these 
cases,  alloc  must  be  specified  as  AllocNone  (else  a  BadMatch  error). 

For  the  other  visual  classes,  Pseudocolor,  DirectColor,  and  Grayscale,  you  can  pass 
either  AllocAll  or  AllocNone  to  the  alloc  argument.  If  you  pass  AllocNone,  the 
colormap  has  no  allocated  entries.  This  allows  your  client  programs  to  allocate  read-only 
colorcells  with  XAllocColor  or  read/write  cells  with  XAllocColorCells,  Alloc- 
ColorPlanes  and  XStoreColors.  If  you  pass  the  constant  AllocAll,  the  entire  color- 
map  is  allocated  writable  (all  the  entries  are  read/write,  nonshareable  and  have  undefined  initial 
RGB  values),  and  the  colors  can  be  set  with  XStoreColors.  However,  you  cannot  free  these 
entries  with  XFreeColors,  and  no  relationships  between  the  entries  are  defined. 

If  the  visual  class  is  Pseudocolor  or  Grayscale  and  alloc  is  AllocAll,  this  function 
simulates  a  call  to  the  function  XAllocColor  cells  returning  all  pixel  values  from  1  to 
(map_entries  -  1) .  For  a  visual  class  of  DirectColor,  the  processing  for  AllocAll 
simulates  a  call  to  the  function  XAllocColorPlanes,  returning  a  pixel  value  of  0  and  mask 
values  the  same  as  the  red__mask,  green_mask,  and  blue_mask  members  in  visual. 
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The  visual  argument  should  be  as  returned  from  the  Def  aultvisual  macro,  XMatch- 
Visuallnf  o,  or  XGetVisuallnf  o. 

If  the  hardware  colormap  on  the  server  is  immutable,  and  therefore  there  is  no  possibility  that  a 
virtual  colormap  could  ever  be  installed,  XCreateColormap  returns  the  default  colormap. 
Code  should  check  the  returned  ID  against  the  default  colormap  to  catch  this  situation. 

For  more  information  on  creating  colormaps,  see  Volume  One,  Chapter  7,  Color. 

Errors 

BadAlloc 

BadMatch          Didn't  use  AllocNone  for  StaticColor,  StaticGray,  or  True- 
Color, 
visual  type  not  supported  on  screen. 

BadValue 
BadWindow 

Related  Commands 

Def aultColormap,  DisplayCells, XCopyColormapAndFree,  XFreeColormap, 
XGetStandardColormap, XInstallColormap,  XListlnstalledColormaps, 
XSetStandardColormap, XSetWindowColormap, XUninstallColormap. 
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—  Xlib-  Cursors- 


XCreateFontCursor 


Name 

XCreateFontCursor  —  create  a  cursor  from  the  standard  cursor  font. 


Synopsis 

#include  <Xll/cursorf  ont  .h> 
Cursor  XCreateFontCursor  (  display, 

Display  *  display  ; 

unsigned  int  shape; 


shape) 


Arguments 

display      Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

shape  Specifies  which  character  in  the  standard  cursor  font  should  be  used  for  the  cur 

sor. 

Description 

X  provides  a  set  of  standard  cursor  shapes  in  a  special  font  named  "cursor."  Programs  are 
encouraged  to  use  this  interface  for  their  cursors,  since  the  font  can  be  customized  for  the  indi 
vidual  display  type  and  shared  between  clients. 

The  hotspot  comes  from  the  information  stored  in  the  font.  The  initial  colors  of  the  cursor  arc 
black  for  the  foreground  and  white  for  the  background.  XRecolorCursor  can  be 
used  to  change  the  colors  of  the  cursor  to  those  desired. 

For  more  information  about  cursors  and  their  shapes  in  fonts,  see  Appendix  I,  The  Cursor  Font. 
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XCreateFontCursor  (continued)  Xlib  -  Cursors 

Errors 

BadAlloc 

BadFont 

BadValue          The  shape  argument  does  not  specify  a  character  in  the  standard  cursor  font. 

Related  Commands 

XCreateGlyphCursor,  XCreatePixmapCursor, XDef ineCursor,  XFreeCursor, 
XQueryBestCursor, XQueryBestSize, XRecolorCursor,  XUndef ineCursor. 
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—  Xlib  -  Graphics  Context- 


XCreateGC 


Name 

XCreateGC  —  create  a  new  graphics  context  for  a  given  screen  with  the  depth  of  the  specified 
drawable. 

Synopsis 

GC  XCreateGC (display,  drawable,  valuemask,  values) 
Display  *display; 
Drawable  drawable; 
unsigned  long  valuemask; 
XGCValues  *  values ; 


Arguments 

di  spl ay 
drawable 

valuemask 
values 


Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

Specifies  a  drawable.  The  created  GC  can  only  be  used  to  draw  in  drawables 
of  the  same  depth  as  this  drawable. 

Specifies  which  members  of  the  GC  are  to  be  set  using  information  in  the 
values  structure,  valuemask  is  made  by  combining  any  number  of  the 
mask  symbols  listed  in  the  Structures  section. 

Specifies  a  pointer  to  an  XGCValues  structure  which  will  provide  compo 
nents  for  the  new  GC. 

Description 

XCreateGC  creates  a  new  graphics  context  resource  in  the  server.  The  returned  GC  can  be 
used  in  subsequent  drawing  requests,  but  only  on  drawables  on  the  same  screen  and  of  the  same 
depth  as  the  drawable  specified  in  the  drawable  argument. 

The  specified  components  of  the  new  graphics  context  in  valuemask  are  set  to  the  values 
passed  in  the  val  ues  argument.  Unset  components  default  as  follows: 


Component        Value 


plane_mask 

foreground 

background 

line_width 

line_style 

cap_style 

join_style 

fill_style 

fill_rule 

arc_mode 

tile 

stipple 


alll's 

o 

i 

0 

LineSolid 

CapButt 

JoinMiter 

FillSolid 

EvenOddRule 

ArcPieSlice 

Pixmap  filled  with  foreground  pixel 

Pixmap  filled  with  1's 


Xlib  Reference  Manual 


109 


XCreateGC 


(continued) 


Xlib  -  Graphics  Context 


Component 

Value 

ts_x_origin 

0 

ts   y   origin 

0 

font 

(implementation 

dependent) 

subwindow  mode 

ClipByChildren 

graphics_exposures 

True 

clip   x   origin 

0 

clip_y_origin 

0 

clip_mask 

None 

dash   offset 

0 

dash   list 

4  (i.e.,  the  list  [4 

,4]) 

An  application  should  minimize  the  number  of  GCs  it  creates,  because  some  servers  cache  a 
limited  number  of  GCs  in  the  display  hardware,  and  can  attain  better  performance  with  a  small 
number  of  GCs. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 

Errors 

BadAlloc          Server  could  not  allocate  memory  for  GC. 

BadDrawable  Specified  drawable  is  invalid. 

BadFont  Font  specified  for  font  component  of  GC  has  not  been  loaded. 

BadMatch  Pixmap  specified  for  tile  component  has  different  depth  or  is  on  different 
screen  from  the  specified  drawable.  Or  pixmap  specified  for  stipple  or 
clip_mask  component  has  depth  other  than  1. 

BadPixmap  Pixmap  specified  for  tile,  stipple,  or  clip_mask  components  is  inva 
lid. 

BadValue  Values  specified  for  function,  line_style,  cap_style, 
join_style,  f ill_style,  f ill_rule,  subwindow_mode,  graph- 
ics_exposures,  dashes,  or  arcjmode  are  invalid,  or  invalid  mask 
specified  for  valuemask  argument. 


Structures 

typedef  struct  { 

int  function;  /* 

unsigned  long  plane  mask;  /* 

unsigned  long  foreground;  /* 

unsigned  long  background;  /* 

int  line_width;  /* 

int  line_style;  /* 

int  cap_style;  /* 

int  join_style;  /* 

int  fill_style;  /* 

int  fill  rule;  /* 


logical  operation  */ 

plane  mask  */ 

foreground  pixel  */ 

background  pixel  */ 

line  width  */ 

LineSolid,  LineOnOf f Dash,  LineDoubleDash  */ 

CapNotLast,  CapButt,  CapRound,  CapPro jecting  */ 

JoinMiter,  JoinRound,  JoinBevel  */ 

FillSolid,  FillTiled,  FillStippled  */ 

EvenOddRule,  WindingRule  */ 
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(continued) 


XCreateGC 


int  arc_mode; 
Pixmap  tile; 
Pixmap  stipple; 
int  ts_x_origin; 
int  ts_y_origin; 
Font  font; 
int  subwindow_mode; 
Bool  graphics_exposures; 
int  clip_x_origin; 
int  clip_y_origin; 
Pixmap  clip_mask; 
int  dash_offset; 
char  dashes; 
}  XGC Value s; 

#define  GCFunction 
#define  GCPlaneMask 
#define  GCForeground 
#define  GCBackground 
#define  GCLineWidth 
#define  GCLineStyle 
#define  GCCapStyle 
#define  GCJoinStyle 
#define  GCFillStyle 
#define  GCFillRule 
#define  GCTile 
#define  GCStipple 
#define  GCTileStipXOrigin 
#define  GCTileStipYOrigin 
#define  GCFont 
#define  GCSubwindowMode 
#define  GCGraphicsExposures 
#define  GCClipXOrigin 
#define  GCClipYOrigin 
tdefine  GCClipMask 
#define  GCDashOffset 
#define  GCDashList 
#define  GCArcMode 


/*  ArcPieSlice,  ArcChord  */ 

/*  tile  pixmap  for  tiling  operations  */ 

/*  stipple  1  plane  pixmap  for  stipping  */ 

/*  offset  for  tile  or  stipple  operations  */ 

/*  default  text  font  for  text  operations  */ 

/*  ClipByChildren,  Includelnferiors  */ 

/*  generate  events  on  XCopyArea,  XCopyPlane  */ 

/*  origin  for  clipping  */ 

/*  bitmap  clipping;  other  calls  for  rects  */ 

/*  patterned/dashed  line  information  */ 


(1L«20) 
(1L«22) 


Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XFreeGC,  XGContextFromGC,  XGetGCValues, 
XSetArcMode,  XSetBackground, XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule,  XSetFillStyle,  XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes,  XSetPlane- 
Mask, XSetState, XSetStipple, XSetSubwindowMode,  XSetTSOrigin. 
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XCreateGlyphCursor  \ 

v Xlib  -  Cursors- 
Name 

XCreateGlyphCursor  —  create  a  cursor  from  font  glyphs. 

Synopsis 

Cursor  XCreateGlyphCursor (  display,  source_font ,  mask_font, 
source_charr  mask_char ,  foreground_color,   back- 
ground_color) 

Display  * display ; 

Font  source_font ,  mask_font; 

unsigned  int  source_char,  mask_char; 

XColor  * foreground_color; 

XColor  *background_color; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

source_font  Specifies  the  font  from  which  a  character  is  to  be  used  for  the  cursor. 
mask_font       Specifies  the  mask  font.  Optional;  specify  0  if  not  needed. 
source_char  Specifies  the  index  into  the  cursor  shape  font. 

mask_char       Specifies  the  index  into  the  mask  shape  font.    Optional;  specify  0  if  not 
needed. 

foreground_color 

Specifies  the  red,  green,  and  blue  (RGB)  values  for  the  foreground. 

background_color 

Specifies  the  red,  green,  and  blue  (RGB)  values  for  the  background. 

Description 

XCreateGlyphCursor  is  similar  to  XCreatePixmapCursor,  but  the  source  and  mask 
bitmaps  are  obtained  from  separate  font  characters,  perhaps  in  separate  fonts.  The  mask  font 
and  character  are  optional.  If  mask_char  is  not  specified,  all  pixels  of  the  source  are 
displayed. 

The  x  offset  for  the  hotspot  of  the  created  cursor  is  the  left-bearing  for  the  source  character,  and 
the  y  offset  is  the  ascent,  each  measured  from  the  upper-left  corner  of  the  bounding  rectangle  of 
the  character. 

The  origins  of  the  source  and  mask  (if  it  is  defined)  characters  are  positioned  coincidently  and 
define  the  hotspot.  The  source  and  mask  need  not  have  the  same  bounding  box  metrics,  and 
there  is  no  restriction  on  the  placement  of  the  hotspot  relative  to  the  bounding  boxes. 

Note  that  source_char  and  mask_char  are  of  type  unsigned  int,  not  of  type 
XChar2b.  For  two-byte  matrix  fonts,  source_char  and  mask_char  should  be  formed 
with  the  bytel  member  in  the  most  significant  byte  and  the  byte2  member  in  the  least  signif 
icant  byte. 
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Xlib- Cursors  (continued)  XCreateGlyphCursor 

You  can  free  the  fonts  with  XFreeFont  if  they  are  no  longer  needed  after  creating  the  glyph 
cursor. 

For  more  information  on  fonts  and  cursors,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and 
Text. 

Structures 

typedef   struct    { 

unsigned   long  pixel; 

unsigned   short    red,    green,    blue; 

char    flags;  /*   DoRed,    DoGreen,    DoBlue    */ 

char   pad; 
}    XColor; 

Errors 

BadAlloc 

BadFont 

BadValue          source_charnot  defined  in  source_font. 

mask_ch  a  mot  defined  in  mask_font  (if  mas  k_  font  defined). 

Related  Commands 

XCreateFontCursor, XCreatePixmapCursor, XDef ineCursor, XFreeCursor, 
XQueryBestCursor, XQueryBestSize,  XRecolorCursor,  XUndef ineCursor. 
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XCreatelmage  \ X|jb  _  |mages_ 

Name 

XCreatelmage  —  allocate  memory  for  an  Xlmage  structure. 

Synopsis 

tfinclude  <Xll/Xutil.h> 

Xlmage  *XCreateImage  (display,  visual,  depth,  format,  offset, 
data,  width,  height,  bitmap_pad,  bytes_per_line) 

Display  * display; 

Visual  *visual; 

unsigned  int  depth; 

int  format; 

int  offset; 

char  *data; 

unsigned  int  width; 

unsigned  int  height; 

int  bitmap_pad; 

int  bytes_per_line; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

visual  Specifies  a  pointer  to  a  visual  that  should  match  the  visual  of  the  window  the 

image  is  to  be  displayed  in. 

depth  Specifies  the  depth  of  the  image. 

format  Specifies  the  format  for  the  image.  Pass  one  of  these  constants:  XYPixmap, 

or  ZPixmap. 

offset  Specifies  the  number  of  pixels  beyond  the  beginning  of  the  data  (pointed  to 

by  data)  where  the  image  actually  begins.  This  is  useful  if  the  image  is  not 
aligned  on  an  even  addressable  boundary. 

da  t  a  Specifies  a  pointer  to  the  image  data. 

wi  dth  Specify  the  width  and  height  in  pixels  of  the  image. 

height 

bi  t/nap_pad  Specifies  the  quantum  of  a  scan  line.  In  other  words,  the  start  of  one  scan  line 
is  separated  in  client  memory  from  the  start  of  the  next  scan  line  by  an  integer 
multiple  of  this  many  bits.  You  must  pass  one  of  these  values:  8 , 1 6 ,  or  3  2 . 

jbytes_per_line 

Specifies  the  number  of  bytes  in  the  client  image  between  the  start  of  one 
scan  line  and  the  start  of  the  next.  If  you  pass  a  value  of  0  here,  Xlib  assumes 
that  the  scan  lines  are  contiguous  in  memory  and  thus  calculates  the  value  of 
bytes_per_line  itself. 
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Description 

XCreatelmage  allocates  the  memory  needed  for  an  Xlmage  structure  for  the  specified  dis 
play  and  visual. 

This  function  does  not  allocate  space  for  the  image  itself.  It  initializes  the  structure  with  byte 
order,  bit  order,  and  bitmap  unit  values,  and  returns  a  pointer  to  the  Xlmage  structure.  The  red, 
green,  and  blue  mask  values  are  defined  for  ZPixmap  format  images  only  and  are  derived  from 
the  visual  structure  passed  in. 

For  a  description  of  images,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
Related  Commands 

ImageByteOrder,  XAddPixel,  XDestroylmage,  XGetlmage,  XGetPixel,  XGet- 
Sublmage,  XPutlmage,  XPutPixel,  XSublmage. 
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XCreatePixmap 

Xlib  -  Pixmaps  and  Tiles- 
Name 

XCreatePixmap  —  create  a  pixmap. 

Synopsis 

Pixmap  XCreatePixmap ( display,  drawable ,  width,  height,  depth) 
Display  *  display; 
Drawable  drawable; 
unsigned  int  width,  height; 
unsigned  int  depth; 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi spl ay. 

drawable         Specifies  the  drawable.  May  be  an  inputOnly  window. 

width  Specify  the  width  and  height  in  pixels  of  the  pixmap.  The  values  must  be 

height  nonzero. 

depth  Specifies  the  depth  of  the  pixmap.  The  depth  must  be  supported  by  the  screen 

of  the  specified  drawable.  (Use  XListDepths  if  in  doubt.) 

Description 

XCreatePixmap  creates  a  pixmap  resource  and  returns  its  pixmap  ID.  The  initial  contents 
of  the  pixmap  are  undefined. 

The  server  uses  the  drawable  argument  to  determine  which  screen  the  pixmap  is  stored  on. 
The  pixmap  can  only  be  used  on  this  screen.  The  pixmap  can  only  be  drawn  drawn  into  with 
GCs  of  the  same  depth,  and  can  only  be  copied  to  drawables  of  the  same  depth,  except  in 
XCopyPlane. 

A  bitmap  is  a  single-plane  pixmap.  There  is  no  separate  bitmap  type  in  X  Version  11. 

Pixmaps  should  be  considered  a  precious  resource,  since  many  servers  have  limits  on  the 
amount  of  off-screen  memory  available. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Errors 

BadAlloc 

BadDrawable 

BadValue          width  or  height  is  0. 

depth  is  not  supported  on  screen. 

Related  Commands 

XCreateBitmapFromData, XCreatePixmapFromBitmapData, XFreePixmap, 
XListDepths, XListPixmapFormat, XQueryBestCursor, XQueryBestSize, 
XQueryBestStipple, XQueryBestTile, XReadBitmapFile, XSetTile,  XSet- 
WindowBackgroundPixmap, XSetWindowBorderPixmap, XWriteBitmapFile. 
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—  Xlib  -  Pixmaps  and  Tiles- 


J  XCreatePixmapCursor 


Name 

XCreatePixmapCursor  —  create  a  cursor  from  two  bitmaps. 

Synopsis 

Cursor  XCreatePixmapCursor ( display,  source,  mask, 

foreground_color,  background_color,  x_hot ,  y_hot) 
Display  * display; 
Pixmap  source; 
Pixmap  mask; 

XColor  * foreground_color; 
XColor  *background_color; 
unsigned  int  x_hot ,  y_hot ; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi  spl  ay. 

source  Specifies  the  shape  of  the  source  cursor.  A  pixmap  of  depth  1. 

mask  Specifies  the  bits  of  the  cursor  that  are  to  be  displayed  (the  mask  or  stipple). 

A  pixmap  of  depth  1. 

-foreground_color 

Specifies  the  red,  green,  and  blue  (RGB)  values  for  the  foreground. 

jbacJegrour!d_co-Zor 

Specifies  the  red,  green,  and  blue  (RGB)  values  for  the  background. 

x_hot  Specify  the  coordinates  of  the  cursor's  hotspot  relative  to  the  source's  origin. 

y_hot  Must  be  a  point  within  the  source. 


Description 

XCreatePixmapCursor  creates  a  cursor  and  returns  a  cursor  ID.  Foreground  and  back 
ground  RGB  values  must  be  specified  using  £oreground_color  and  back- 
ground_color,  even  if  the  server  only  has  a  monochrome  screen.  The  fore- 
ground_color  is  used  for  the  1  bits  in  the  source,  and  the  background  is  used  for  the  0  bits. 
Both  source  and  mask  (if  specified)  must  have  depth  1,  but  can  have  any  root.  The  mask  pix 
map  defines  the  shape  of  the  cursor;  that  is,  the  1  bits  in  the  mask  define  which  source  pixels 
will  be  displayed.  If  no  mask  is  given,  all  pixels  of  the  source  are  displayed.  The  mask,  if 
present,  must  be  the  same  size  as  the  source. 

The  pixmaps  can  be  freed  immediately  if  no  further  explicit  references  to  them  are  to  be  made. 
For  more  information  on  cursors,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

typedef  struct  { 

unsigned  long  pixel; 

unsigned  short  red,  green,  blue; 

char  flags;  /*  DoRed,  DoGreen,  DoBlue  */ 
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XCreatePixmapCursor  (continued)  Xlib  -  Pixmaps  and  Tiles 

char  pad; 
}    XColor; 

Errors 

BadAlloc 

BadMatch         Mask  bitmap  must  be  the  same  size  as  source  bitmap. 
BadPixmap 

Related  Commands 

XCreateBitmapFromData, XDef ineCursor, XCreateFontCursor, XCreate- 
Pixmap,  XCreatePixmapCursor, XFreeCursor, XFreePixmap,  XQueryBest- 
Cursor, XQueryBestCursor, XQueryBestSize, XQueryBestSize, XRead- 
BitmapFile, XRecolorCursor, XUndef ineCursor. 
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—  Xlib  -  Pixmaps  and  Bitmaps - 


XCreatePixmapFromBJtmapData 


Name 

XCreatePixmapFromBitmapData  —  create  a  pixmap  with  depth  from  bitmap  data. 

Synopsis 

Pixmap  XCreatePixmapFromBitmapData ( display,  drawable,  data, 

width,  height,  fg,  bg,  depth) 
Display  * display; 
Drawable  drawable; 
char  *data; 

unsigned  int  width,  height; 
unsigned  long  fg,  bg; 
unsigned  int  depth; 

Arguments 

display  Specifies  a  connection  to  an  Display  structure,  returned  from  XOpen- 

Display. 

drawable          Specifies  a  drawable  ID  which  indicates  which  screen  the  pixmap  is  to  be 
used  on. 

data  Specifies  the  data  in  bitmap  format. 

width  Specify  the  width  and  height  in  pixels  of  the  pixmap  to  create. 

height 

fg  Specify  the  foreground  and  background  pixel  values  to  use. 

bg 

depth  Specifies  the  depth  of  the  pixmap.  Must  be  valid  on  the  screen  specified  by 

drawable. 

Description 

XCreatePixmapFromBitmapData  creates  a  pixmap  of  the  given  depth  using  bitmap  data 
and  foreground  and  background  pixel  values. 

The  following  format  for  the  data  is  assigned,  where  the  variables  are  members  of  the  XI mage 
structure  described  in  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text: 

format =XYP  ixmap 

bit_order=LSBFirst 

byte_order=LSBFirst 

bitmap_unit=8 

bitmap_pad=8 

xoffset=0 

no   extra   bytes   per    line 

XCreatePixmapFromBitmapData  creates  an  image  from  the  data  and  uses  XPutlmage 
to  place  the  data  into  the  pixmap.  For  example: 


Xlib  Reference  Manual  1 19 


XCreatePixmapFromBitmapData    (continued) 


Xlib  -  Pixmaps  and  Bitmaps 


#define  gray_width  16 

#define  gray_height  16 

#define  gray_x_hot  8 

#define  gray_y_hot  8 

static  char  gray_bits[]  =  • 
Oxf8,  Oxlf,  Oxe3,  Oxc7, 
Oxfd,  0x33,  Oxcc,  Ox7f, 
Ox7f,  Oxfe,  0x37,  Oxec, 
Oxf3,  Oxe3,  Oxc7,  Oxf8, 


Oxcf, 
Oxfe, 
Oxbb, 

Oxlf} 


Oxf3, 
Ox7f, 
Oxdd, 


Ox9f, 
Oxfe, 
Ox9c, 


Oxf9, 
Ox7e, 
0x39, 


Oxbf, 
Ox7e, 
Oxcf, 


unsigned  long  foreground,  background; 
unsigned  int  depth; 

/*  open  display,  determine  colors  and  depth  */ 

Pixmap  XCreatePixmapFromBitmapData (display,  window,  gray_bits, 

gray_width,  gray_height,  foreground,  background,  depth) ; 

If  you  want  to  use  data  of  a  different  format,  it  is  straightforward  to  write  a  routine  that  does 
this  yourself,  using  images. 

Pixmaps  should  be  considered  a  precious  resource,  since  many  servers  have  limits  on  the 
amount  of  off-screen  memory  available. 

Errors 

BadAlloc 
BadDrawable 

BadValue          The  width  or  height  of  pixmap  are  zero,  or  depth  is  not  a  valid  depth  on 
the  screen  specified  by  drawable. 

Related  Commands 

XCreateBitmapFromData, XCreateFontCursor, XCreatePixmap,  XCreate- 
PixmapCursor, XDef ineCursor, XFreeCursor, XFreePixmap,  XListPixmap- 
Formats, XQueryBestCursor, XQueryBestSize,  XReadBitmapFile,  XRecolor- 
Cursor, XUndef ineCursor. 
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—  Xlib-  Regions- 


J  XCreateRegion 


Name 

XCreateRegion  —  create  a  new  empty  region. 

Synopsis 

Region  XCreateRegion  () 

Description 

XCreateRegion  creates  a  new  region  of  undefined  size.  XPolygonRegion  can  be  used  to 
create  a  region  with  a  defined  shape  and  size.  Many  of  the  functions  that  perform  operations  on 
regions  can  also  create  regions. 

For  a  description  of  regions,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XDestroyRegion, XEmptyRegion,  XEqualRegion, Xlntersect- 
Region,  XOf f setRegion,  XPointlnRegion,  XPolygonRegion,  XRectlnRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion,  XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 


Xlib  Reference  Manual  121 


XCreateSimpleWindow  . vr. 

v Xlib  -  Window  Existence— 

Name 

XCreateSimpleWindow  — create  an  unmapped  InputOutput  window. 

Synopsis 

Window  XCreateSimpleWindow (display,  parent,  x,  y,  width,  height, 
border_width,  border,  background) 

Display  * display; 

Window  parent; 

int  x,  y; 

unsigned   int    width,    height,    border_width; 

unsigned  long  border; 

unsigned  long  background; 

Arguments 

di  spl  ay          Specifies  a  pointer  to  the  Di  spl  ay  structure;  returned  from  XOpenDi  spl  ay. 

parent  Specifies  the  parent  window  ID.  Must  be  an  InputOutput  window. 

x  Specify  the  x  and  y  coordinates  of  the  upper-left  pixel  of  the  new  window's 

y  border  relative  to  the  origin  of  the  parent  (inside  the  parent  window's  border). 

width  Specify  the  width  and  height,  in  pixels,  of  the  new  window.  These  are  the 

height  inside  dimensions,  not  including  the  new  window's  borders,  which  are  entirely 

outside  of  the  window.  Must  be  nonzero.  Any  part  of  the  window  that  extends 

outside  its  parent  window  is  clipped. 

border_wi  dth 

Specifies  the  width,  in  pixels,  of  the  new  window's  border. 

border  Specifies  the  pixel  value  for  the  border  of  the  window. 

background  Specifies  the  pixel  value  for  the  background  of  the  window. 

Description 

XCreateSimpleWindow  creates  an  unmapped  InputOutput  subwindow  of  the  specified 
parent  window.  Use  XCreateWindow  if  you  want  to  set  the  window  attributes  while  creating 
a  window.  (After  creation,  XChangeWindowAttributes  can  be  used.) 

XCreateSimpleWindow  returns  the  ID  of  the  created  window.  The  new  window  is  placed 
on  top  of  the  stacking  order  relative  to  its  siblings.  Note  that  the  window  is  unmapped  when  it 
is  created — use  Mapwindow  to  display  it.  This  function  generates  a  XCreateNotify  event. 

The  initial  conditions  of  the  window  are  as  follows: 

The  window  inherits  its  depth,  class,  and  visual  from  its  parent.  All  other  window  attributes 
have  their  default  values. 

All  properties  have  undefined  values. 

The  new  window  will  not  have  a  cursor  defined;  the  cursor  will  be  that  of  the  window's  parent 
until  the  cursor  attribute  is  set  with  XDefineCursor  or  XChangeWindowAttributes. 
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Xlib- Window  Existence  (continued)  XCreateSimpleWindOW 

If  no  background  or  border  is  specified,  CopyFromParent  is  implied. 

For  more  information,  see  Volume  One,  Chapter  2,  X  Concepts,  and  Volume  One,  Chapter  3, 
Basic  Window  Program. 

Errors 

BadAlloc 

BadMatch 

BadValue          width  or  height  is  zero. 

Badwindow       Specified  parent  is  an  Input  Only  window. 

Related  Commands 

XCreateWindow, XDestroySubwindows, XDestroyWindow. 
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XCreateWindow  "\ 

v Xlib  -  Window  Existence— 

Name 

XCreateWindow  —  create  a  window  and  set  attributes. 

Synopsis 

Window  XCreateWindow  (display,  parent,  x,  y,  width,  height, 
border_width,  depth,  class,  visual,  valuemask, 
attributes) 

Display  *  display; 

Window  parent; 

int  x,  y; 

unsigned   int    width,    height; 

unsigned   int   border_width; 

int    depth; 

unsigned  int  class; 

Visual  ^visual 

unsigned  long  valuemask; 

XSetWindowAttributes  *  attributes; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

parent  Specifies  the  parent  window.  Parent  must  be  inputOutput  if  class  of  win 

dow  created  is  to  be  InputOutput. 

x  Specify  the  x  and  y  coordinates  of  the  upper-left  pixel  of  the  new  window's 

y  border  relative  to  the  origin  of  the  parent  (upper  left  inside  the  parent's  border). 

width  Specify  the  width  and  height,  in  pixels,  of  the  window.  These  are  the  new  win- 

height  dow's  inside  dimensions.  These  dimensions  do  not  include  the  new  window's 

borders,  which  are  entirely  outside  of  the  window.  Must  be  nonzero,  otherwise 

the  server  generates  a  BadValue  error. 

border_  width 

Specifies  the  width,  in  pixels,  of  the  new  window's  border.  Must  be  0  for 
inputOnly  windows,  otherwise  a  BadMatch  error  is  generated. 

depth  Specifies  the  depth  of  the  window,  which  is  less  than  or  equal  to  the  parent's 

depth.  A  depth  of  CopyFromParent  means  the  depth  is  taken  from  the  par 
ent.  Use  XListDepths  is  choosing  an  unusual  depth.  The  specified  depth 
paired  with  the  visual  argument  must  be  supported  on  the  screen. 

class  Specifies  the  new  window's  class.    Pass  one  of  these  constants:    Input- 

Output,  InputOnly,  or  CopyFromParent. 

visual  Specifies  a  connection  to  an  visual  structure  describing  the  style  of  colormap  to 

be  used  with  this  window.  CopyFromParent  is  valid. 

valuemask  Specifies  which  window  attributes  are  defined  in  the  attributes  argument. 
If  valuemask  is  0,  attributes  is  not  referenced.  This  mask  is  the  bitwise 
OR  of  the  valid  attribute  mask  bits  listed  in  the  Structures  section  below. 
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attributes  Attributes  of  the  window  to  be  set  at  creation  time  should  be  set  in  this  struc 
ture.  The  value/nasJt  should  have  the  appropriate  bits  set  to  indicate  which 
attributes  have  been  set  in  the  structure. 

Description 

To  create  an  unmapped  subwindow  for  a  specified  parent  window  use  XCreateWindow  or 
XCreateSimpleWindow.  XCreateWindow  is  a  more  general  function  that  allows  you  to 
set  specific  window  attributes  when  you  create  the  window.  If  you  do  not  want  to  set  specific 
attributes  when  you  create  a  window,  use  XCreateSimpleWindow,  which  creates  a  window 
that  inherits  its  attributes  from  its  parent.  XCreateSimpleWindow  creates  only  Input- 
Output  windows  that  use  the  default  depth  and  visual. 

XCreateWindow  returns  the  ID  of  the  created  window.  XCreateWindow  causes  the  X 
server  to  generate  a  CreateNotif  y  event.  The  newly  created  window  is  placed  on  top  of  its 
siblings  in  the  stacking  order. 

Extension  packages  may  define  other  classes  of  windows. 

The  visual  should  be  Def  aultvisual  or  one  returned  by  XGetvisuallnf  o  or  XMatch- 
Visuallnfo.  The  depth  should  be  DefaultDepth,  1,  or  a  depth  returned  by  XList- 
Depths.  In  current  implementations  of  Xlib,  if  you  specify  a  visual  other  than  the  one  used  by 
the  parent,  you  must  first  find  (using  XGetRGBColormaps)  or  create  a  colormap  matching 
this  visual  and  then  set  the  colormap  window  attribute  in  the  attributes  and  valuemask 
arguments.  Otherwise,  you  will  get  a  BadMatch  error. 

For  more  information,  see  Volume  One,  Chapter  4,  Window  Attributes. 

Structures 

/* 

*  Data  structure  for  setting  window  attributes. 

*/ 
typedef  struct  { 

Pixmap  background_pixmap;  /*  background  or  None  or  ParentRelative  */ 

unsigned  long  background_pixel;  /*  background  pixel  */ 

Pixmap  border_pixmap;  /*  border  of  the  window  */ 

unsigned  long  border_pixel;  /*  border  pixel  value  */ 

int  bit_gravity;  /*  one  of  bit  gravity  values  */ 

int  win  gravity;  /*  one  of  the  window  gravity  values  */ 

int  backing  store;  /*  NotUseful,  WhenMapped,  Always  */ 

unsigned  long  backing_planes;  /*  planes  to  be  preseved  if  possible  */ 

unsigned  long  backing_pixel;  /*  value  to  use  in  restoring  planes  */ 

Bool  save_under;  /*  should  bits  under  be  saved  (popups)  */ 

long  event  mask;  /*  set  of  events  that  should  be  saved  */ 

long  do  not  propagate_mask;  /*  set  of  events  that  should  not  propagate  i 

Bool  override_redirect;  /*  boolean  value  for  override-redirect  */ 

Colormap  colormap;  /*  colormap  to  be  associated  with  window  */ 

Cursor  cursor;  /*  cursor  to  be  displayed  (or  None)  */ 
}  XSetWindowAttributes; 
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/*  Definitions  for  valuemask  argument  */ 

tdefine  CWBackPixmap  (1L«0) 

tdefine  CWBackPixel  (1L«1) 

tdefine  CWBorderPixmap  (1L«2) 

#define  CWBorderPixel  (1L«3) 

#define  CWBitGravity  (1L«4) 

#define  CWWinGravity  (1L«5) 

#define  CWBackingStore  (1L«6) 

tdefine  CWBackingPlanes  (1L«7) 

#define  CWBackingPixel  (1L«8) 

tdefine  CWOverrideRedirect  (1L«9) 

tdefine  CWSaveUnder  (1L«10) 

#define  CWEventMask  (1L«11) 

tdefine  CWDontPropagate  (1L«12) 

tdefine  CWColormap  (1L«13) 

tdefine  CWCursor  (1L«14) 

Errors 

BadAlloc          Attribute  besides  win_gravity,  event_mask,  do_not_propagate 
mask,  override_redirect  or  cursor  specified  for  InputOnly  win 
dow. 

BadColormap   depth  nonzero  for  InputOnly. 
BadCursor        Parent  of  InputOutput  is  InputOnly. 
BadMatch          border_width  is  nonzero  for  InputOnly. 
BadPixmap        depth  not  supported  on  screen  for  InputOutput. 
BadValue          width  or  height  is  0. 
Badwindow        visual  not  supported  on  screen. 

Related  Commands 

XCreateSimpleWindow, XDestroySubwindows, XDestroyWindow, XList- 
Depths. 
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-x,,b  -  cursors /  XDefineCursor 

Name 

XDefineCursor  —  assign  a  cursor  to  a  window. 

Synopsis 

XDefineCursor (display,  w,  cursor) 
Display  * display; 
Window  w; 
Cursor  cursor; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  ID  of  the  window  in  which  the  cursor  is  to  be  displayed. 

cursor  Specifies  the  cursor  to  be  displayed  when  the  pointer  is  in  the  specified  win 

dow.  Pass  None  to  have  the  parent's  cursor  displayed  in  the  window,  or  for 
the  root  window,  to  have  the  default  cursor  displayed. 

Description 

Sets  the  cursor  attribute  of  a  window,  so  that  the  specified  cursor  is  shown  whenever  this  win 
dow  is  visible  and  the  pointer  is  inside.  If  XDefineCursor  is  not  called,  the  parent's  cursor 
is  used  by  default. 

For  more  information  on  available  cursors,  see  Appendix  I,  The  Cursor  Font. 
Errors 

BadCursor 
BadWindow 

Related  Commands 

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XFree- 
Cursor, XQueryBestCursor, XQueryBestSize, XRecolorCursor, XUndef ine- 
Cursor. 
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XDeleteAssoc  , vr. 

v Xlib  -  Association  Tables- 
Name 

XDeleteAssoc  —  delete  an  entry  from  an  association  table. 

Synopsis 

XDeleteAssoc ( display,  table ,  x_id) 
Display  * display ; 
XAssocTable  *  table; 
XID  x_id; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDi splay. 

table  Specifies  one  of  the  association  tables  created  by  XCreateAssocTable. 

x_i  d  Specifies  the  X  resource  ID  of  the  association  to  be  deleted. 

Description 

This  function  is  provided  for  compatibility  with  X  Version  10.  To  use  it  you  must  include  the 
file  <XlllX10.h>  and  link  with  the  library  -loldX. 

XDeleteAssoc  deletes  an  association  in  an  XAssocTable  keyed  on  its  XID.  Redundant 
deletes  (and  deletes  of  nonexistent  X ID'S)  are  meaningless  and  cause  no  problems.  Deleting 
associations  in  no  way  impairs  the  performance  of  an  XAssocTable. 

For  more  information  on  association  tables,  see  Volume  One,  Appendix  R,X10  Compatibility. 
Structures 

typedef  struct  { 

XAssoc  ^buckets;          /*  pointer  to  first  bucket  in  array  */ 
int  size;  /*  table  size  (number  of  buckets)  */ 

}  XAssocTable; 

Related  Commands 

XCreateAssocTable, XDestroyAssocTable, XLookUpAssoc, XMakeAssoc. 
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Name 

XDeleteContext  —  delete  a  context  entry  for  a  given  window  and  type. 

Synopsis 

int  XDeleteContext  {  display,  wr  context) 
Display  *  display; 
Window  w; 
XContext  context; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi  splay. 

w  Specifies  the  window  with  which  the  data  is  associated. 

context  Specifies  the  context  type  to  which  the  data  belongs. 

Description 

XDeleteContext  deletes  the  entry  for  the  given  window  and  type  from  the  context  data 
structure  defined  in  <Xll/Xutil.h>.  This  function  returns  XCNOENT  if  the  context  could  not  be 
found,  or  zero  if  it  succeeds.  XDeleteContext  does  not  free  the  memory  allocated  for  the 
data  whose  address  was  saved. 

See  Volume  One,  Chapter  13,  Other  Programming  Techniques,  for  a  description  of  context 
management. 

Structures 

typedef  int  XContext; 

Related  Commands 

XFindContext,  XSaveContext,  XUniqueContext. 
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XDeleteModifiermapEntry  \ X|lb  _  ResourM  Manager_ 

Name 

XDeleteModifiermapEntry  —  delete  an  entry  from  an  XModif  ierKeymap  structure. 

Synopsis 

XModif  ierKeymap  *XDeleteModif  iermapEntry  (/nod/nap, 

keysym_entry,  modifier) 
XModif  ierKeymap  * modmap; 
KeyCode  keysym_entry; 
int  modifier; 

Arguments 

modmap  Specifies  a  pointer  to  an  XModif  ierKeymap  structure. 

k  eysym_  entry 

Specifies  the  keycode  of  the  key  to  be  deleted  from  modmap. 

modifier  Specifies  the  modifier  you  no  longer  want  mapped  to  the  keycode  specified  in 
keysym_entry.  This  should  be  one  of  the  constants:  Shif  tMaplndex, 
LockMapIndex,  ControlMapIndex,  ModlMapIndex,  Mod2Map- 
Index,  ModSMapIndex,  Mod4MapIndex,  or  ModSMapIndex. 

Description 

XDeleteModifiermapEntry  returns  an  XModif  ierKeymap  structure  suitable  for  cal 
ling  XSetModif  ierMapping,  in  which  the  specified  keycode  is  deleted  from  the  set  of  key- 
codes  that  is  mapped  to  the  specified  modifier  (like  Shift  or  Control).  XDelete 
ModifiermapEntry  itself  does  not  change  the  mapping. 

This  function  is  normally  used  by  calling  XGetModif  ierMapping  to  get  a  pointer  to  the 
current  XModif  ierKeymap  structure  for  use  as  the  modmap  argument  to  XDelete 
ModifiermapEntry. 

Note  that  the  structure  pointed  to  by  modmap  is  freed  by  XDeleteModifiermapEntry.  It 
should  not  be  freed  or  otherwise  used  by  applications  after  this  call. 

For  a  description  of  the  modifier  map,  see  XSetModif  ierMapping. 
Structures 

typedef  struct  { 

int  max_keypermod;      /*  server's  max  number  of  keys  per  modifier  */ 
KeyCode  *modif iermap;   /*  an  8  by  max_keypermod  array  of 

*  keycodes  to  be  used  as  modifiers  */ 

}  XModif ierKeymap; 

#define  ShiftMapIndex  0 

#define  LockMapIndex  1 

tdefine  ControlMapIndex  2 

#define  ModlMapIndex  3 

#define  Mod2MapIndex  4 

tdefine  ModSMapIndex  5 
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tdefine  Mod4MapIndex        6 
tdefine  ModSMapIndex 

Related  Commands 

XFreeModif  iermap,  XGetKeyboardMapping,  XGetModif  ierMapping, 
XKeycodeToKeysym,  XKeysymToKeycode,  XKeysymToString,  XLookupKeysym, 
XLookupString, XNewModif iermap, XQueryKeymap, XRebindKeySym, 
XRef reshKeyboardMapping, XSetModif ierMapping,  XStringToKeysym, 
I nsertModif iermapEntry. 
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XDeleteProperty  V 


Name 

XDeleteProperty  —  delete  a  window  property. 

Synopsis 

XDeleteProperty ( display,  w,  property) 
Display  * display ; 
Window  w; 
Atom  property; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  whose  property  you  want  to  delete. 

property         Specifies  the  atom  of  the  property  to  be  deleted. 

Description 

XDeleteProperty  deletes  a  window  property,  so  that  it  no  longer  contains  any  data.  Its 
atom,  specified  by  property,  still  exists  after  the  call  so  that  it  can  be  used  again  later  by  any 
application  to  set  the  property  once  again.  If  the  property  was  defined  on  the  specified  window, 
XDeleteProperty  generates  a  PropertyNotify  event. 

See  the  introduction  to  properties  in  Volume  One,  Chapter  2,  X  Concepts,  or  more  detailed 
information  in  Volume  One,  Chapter  10,  Interclient  Communication. 

Errors 

BadAtom 
BadWindow 

Related  Commands 

XChangeProperty, XGetAtomName, XGetFontProperty,  XGetWindowProperty, 
XInternAtom,  XListProperties,  XRotateWindowProperties, XSetStandard- 
Properties. 
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J  XDestroyAssocTable 


Name 

XDestroyAssocTable  —  free  the  memory  allocated  for  an  association  table. 

Synopsis 

XDestroyAssocTable (table) 
XAssocTable  *table; 

Arguments 

tabl  e  Specifies  the  association  table  whose  memory  is  to  be  freed. 

Description 

This  function  is  provided  for  compatibility  with  X  Version  10.  To  use  it  you  must  include  the 
file  <Xll/X10.h>  and  link  with  the  library  -loldX. 

Using  an  XAssocTable  after  it  has  been  destroyed  will  have  unpredictable  consequences. 
For  more  information  on  association  tables,  see  Volume  One,  Appendix  B,  XI 0  Compatibility. 

Structures 

typedef  struct  { 

XAssoc  ^buckets;        /*  pointer  to  first  bucket  in  array  */ 
int  size;  /*  table  size  (number  of  buckets)  */ 

}  XAssocTable; 

Related  Commands 

XCreateAssocTable, XDeleteAssoc, XLookUpAssoc, XMakeAssoc. 
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XDestroylmage \ x,,b-,mages- 

Name 

XDestroylmage  —  deallocate  memory  associated  with  an  image. 

Synopsis 

int  XDestroylmage (ximage) 
Xlmage  * ximage; 

Arguments 

ximage  Specifies  a  pointer  to  the  image. 

Description 

XDestroylmage  deallocates  the  memory  associated  with  an  Ximage  structure.  This  mem 
ory  includes  both  the  memory  holding  the  ximage  structure,  and  the  memory  holding  the 
actual  image  data.  (If  the  image  data  is  statically  allocated,  the  pointer  to  the  data  in  the 
Ximage  structure  must  be  set  to  zero  before  calling  XDestroylmage.) 

For  more  information  on  images,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
Related  Commands 

ImageByteOrder,  XAddPixel,  XCreatelmage,  XGet  Image,  XGetPixel,  XGet- 
Sublmage, XPut Image, XPutPixel, XSub Image. 
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Name 

XDestroyRegion  —  deallocate  storage  associated  with  a  region. 

Synopsis 

XDestroyRegion ( r) 
Region   r; 

Arguments 

r  Specifies  the  region  to  be  destroyed. 

Description 

XDestroyRegion  frees  the  memory  associated  with  a  region  and  invalidates  pointer  r. 

See  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  for  a  description  of  regions. 


Related  Commands 

XClipBox,  XCreateRegion,  XEmptyRegion,  XEqualRegion, Xlntersect- 
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, 
XSetRegion, XShrinkRegion,  XSubtractRegion,  XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 
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Xlib  -  Window  Existence  — 


Name 

XDestroySubwindows  —  destroy  all  subwindows  of  a  window. 

Synopsis 

XDestroySubwindows ( display,  w) 
Display  * display ; 
Window  w; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  ID  of  the  window  whose  subwindows  are  to  be  destroyed. 

Description 

This  function  destroys  all  descendants  of  the  specified  window  (recursively),  in  bottom  to  top 
stacking  order. 

XDestroySubwindows  generates  exposure  events  on  window  »/,  if  any  mapped  subwindows 
were  actually  destroyed.  This  is  much  more  efficient  than  deleting  many  subwindows  one  at  a 
time,  since  much  of  the  work  need  only  be  performed  once  for  all  of  the  windows  rather  than 
for  each  window.  It  also  saves  multiple  exposure  events  on  the  windows  about  to  be  destroyed. 
The  subwindows  should  never  again  be  referenced. 

xcioseDisplay  automatically  destroys  all  windows  that  have  been  created  by  that  client  on 
the  specified  display  (unless  called  after  a  fork  system  call). 

Never  call  XDestroySubwindows  with  the  window  argument  set  to  the  root  window!  This 
will  destroy  all  the  applications  on  the  screen,  and  if  there  is  only  one  screen,  often  the  server 
as  well. 

Errors 

BadWindow 

Related  Commands 

XCreateSimpleWindow, XCreateWindow,  XDestroyWindow. 
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J  XDestroyWindow 


Name 

XDestroyWindow  —  unmap  and  destroy  a  window  and  all  subwindows. 

Synopsis 

XDestroyWindow ( display,  window) 
Display  *display; 
Window  window; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

window  Specifies  the  ID  of  the  window  to  be  destroyed. 

Description 

If  window  is  mapped,  an  UnmapWindow  request  is  performed  automatically.  The  window 
and  all  inferiors  (recursively)  are  then  destroyed,  and  a  DestroyNotif y  event  is  generated 
for  each  window.  The  ordering  of  the  DestroyNotif  y  events  is  such  that  for  any  given  win 
dow,  DestroyNotif  y  is  generated  on  all  inferiors  of  the  window  before  being  generated  on 
the  window  itself.  The  ordering  among  siblings  and  across  subhierarchies  is  not  otherwise  con 
strained. 

The  windows  should  never  again  be  referenced. 

Destroying  a  mapped  window  will  generate  exposure  events  on  other  windows  that  were 
obscured  by  the  windows  being  destroyed.  XDestroyWindow  may  also  generate  Enter- 
Notify  events  if  window  was  mapped  and  contained  the  pointer. 

No  windows  are  destroyed  if  you  try  to  destroy  the  root  window. 

Errors 

BadWindow 

Related  Commands 

XCreateSimpleWindow,  XCreateWindow,  XDestroySubwindows. 
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XDisableAccessControl  \ X||b  _  Host  Accass_ 

Name 

XDisableAccessControl  —  allow  access  from  any  host. 

Synopsis 

XDisableAccessControl (display) 
Display   * display; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

Description 

XDisableAccessControl  instructs  the  server  to  allow  access  from  clients  on  any  host. 
This  disables  use  of  the  host  access  list. 

This  routine  can  only  be  called  from  a  client  running  on  the  same  host  as  the  server. 

For  more  information  on  access  control,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 

Errors 

BadAccess 

Related  Commands 

XAddHost, XAddHosts,  XEnableAccessControl, XListHosts,  XRemoveHost, 
XRemoveHosts, XSetAccessControl. 
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XDisplayKeycodes 


Name 

XDisplayKeycodes  —  obtain  the  range  of  legal  keycodes  for  a  server. 

Synopsis 

XDisplayKeycodes (display,  min_keycodes ,  max_keycodes) 
Display  *display; 
int  *min_keycoder  *max_keycode;   /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

min_keycode        Returns  the  minimum  keycode. 
max_keycode        Returns  the  maximum  keycode. 

Description 

XDisplayKeycodes  returns  the  min_keycode  and  max_keycode  supported  by  the 
specified  server.  The  minimum  keycode  returned  is  never  less  than  8,  and  the  maximum  key- 
code  returned  is  never  greater  than  255.  Not  all  keycodes  in  this  range  are  required  to  have  cor 
responding  keys. 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
Related  Commands 

XKeycodeToKeysym,  XKeysymToKeycode, XLookupString. 
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XDisplayName  \ 


•Xlib- Error  Handling- 


Name 

XDisplayName  —  report  the  display  name  (when  connection  to  a  display  fails). 

Synopsis 

char  *XDisplayName  ( string) 
char  *string; 

Arguments 

string  Specifies  the  character  string. 

Description 

XDisplayName  is  normally  used  to  report  the  name  of  the  display  the  program  attempted  to 
open  with  xopenDisplay.  This  is  necessary  because  X  error  handling  begins  only  after  the 
connection  to  the  server  succeeds.  If  a  NULL  string  is  specified,  XDisplayName  looks  in  the 
DISPLAY  environment  variable  and  returns  the  display  name  that  the  user  was  requesting. 
Otherwise,  XDisplayName  returns  its  own  argument.  This  makes  it  easier  to  report  to  the 
user  precisely  which  server  the  program  attempted  to  connect  to. 

For  more  information,  see  Volume  One,  Chapter  3,  Basic  Window  Program. 
Related  Commands 

XGetErrorDatabaseText, XGetErrorText, XSetAf terFunction, XSetError- 
Handler,  XSetlOErrorHandler, XSynchronize. 
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—  Xlib  -  Drawing  Primitives ' 

Name 

XDraw  —  draw  a  polyline  or  curve  between  vertex  list  (from  XI 0 ) . 
Synopsis 

Status  XDraw ( display,  drawable,  gcf  vllst,  vcount) 
Display  *dlsplay; 
Drawable  drawable; 
GC  gc; 

Vertex  *vllst; 
int  vcount ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawable  Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

vllst  Specifies  a  pointer  to  the  list  of  vertices  that  indicates  what  to  draw. 

vcount  Specifies  how  many  vertices  are  in  vllst. 

Description 

This  function  is  provided  for  compatibility  with  X  Version  10.  To  use  it  you  must  include  the 
file  <Xll/X10.h>  and  link  with  the  library  -loldX.  Its  performance  is  likely  to  be  low. 

XDraw  draws  an  arbitrary  polygon  or  curve.  The  figure  drawn  is  defined  by  the  specified  list  of 
vertices  (vllst).  The  points  are  connected  by  lines  as  specified  in  the  flags  each  the  Vertex 
structure. 

The  Vertex  structure  contains  an  x,y  coordinate  and  a  bitmask  called  flags  that  specifies 
the  drawing  parameters. 

The  x  and  y  elements  of  Vertex  are  the  coordinates  of  the  vertex  that  are  relative  to  either  the 
previous  vertex  (if  VertexRelative  is  1)  or  the  upper-left  inside  corner  of  the  drawable  (if 
VertexRelative  is  0).  If  VertexRelative  is  0  the  coordinates  are  said  to  be  absolute. 
The  first  vertex  must  be  an  absolute  vertex. 

If  the  VertexDontDraw  bit  is  1,  no  line  or  curve  is  drawn  from  the  previous  vertex  to  this 
one.  This  is  analogous  to  picking  up  the  pen  and  moving  to  another  place  before  drawing 
another  line. 

If  the  VertexCurved  bit  is  1,  a  spline  algorithm  is  used  to  draw  a  smooth  curve  from  the  pre 
vious  vertex,  through  this  one,  to  the  next  vertex.  Otherwise,  a  straight  line  is  drawn  from  the 
previous  vertex  to  this  one.  It  makes  sense  to  set  VertexCurved  to  1  only  if  a  previous  and 
next  vertex  are  both  defined  (either  explicitly  in  the  array,  or  through  the  definition  of  a  closed 
curve — see  below.) 

It  is  permissible  for  VertexDontDraw  bits  and  VertexCurved  bits  to  both  be  1.  This  is 
useful  if  you  want  to  define  the  previous  point  for  the  smooth  curve,  but  you  do  not  want  an 
actual  curve  drawing  to  start  until  this  point. 
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XDraw  (continued)  Xlib  -  Drawing  Primitives 

If  VertexStartClosed  bit  is  1,  then  this  point  marks  the  beginning  of  a  closed  curve.  This 
vertex  must  be  followed  later  in  the  array  by  another  vertex  whose  absolute  coordinates  are 
identical  and  which  has  VertexEndClosed  bit  of  1.  The  points  in  between  form  a  cycle  for 
the  purpose  of  determining  predecessor  and  successor  vertices  for  the  spline  algorithm. 

XDraw  achieves  the  effects  of  the  X10  XDraw,  XDrawDashed,  and  XDrawPatterned 
functions. 

XDraw  uses  the  following  graphics  context  components:  function,  plane_mask, 
line_width,  line_style,  cap_style,  join_style,  fill_style,  subwindow_ 
mode,  clip_x_origin,  clip_y_origin,  and  clip_mask.  This  function  also  uses 
these  graphics  context  mode-dependent  components:  foreground,  background,  tile, 
stipple,  ts_x_origin,  ts_y_origin,  dash_of  f  set,  and  dash_list. 

A  Status  of  zero  is  returned  on  failure,  and  nonzero  on  success. 

For  more  information,  see  Volume  One,  Appendix  B,  XI 0  Compatibility. 

Structures 

typedef  struct  _Vertex  { 

short  x,y; 

unsigned  short  flags; 
}  Vertex; 

/*  defined  constants  for  use  as  flags  */ 

#define  VertexRelative        0x0001  /*  else  absolute  */ 

#define  VertexDontDraw        0x0002  /*  else  draw  */ 

#define  VertexCurved          0x0004  /*  else  straight  */ 

#define  VertexStartClosed     0x0008  /*  else  not  */ 

#define  VertexEndClosed        0x0010  /*  else  not  */ 

Related  Commands 

XClearArea,  XClearWindow, XCopyArea, XCopyPlane, XDrawArc, XDrawArcs, 
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw- 
Rectangle,  XDrawRectangles, XDrawSegments, XFillArc,  XFillArcs,  XFill- 
Polygon, XFillRectangle,  XFillRectangles. 
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. .     J  XDrawArc 

— Xlib  -  Drawing  Primitives * 

Name 

XDrawArc  —  draw  an  arc  fitting  inside  a  rectangle. 

Synopsis 

XDrawArc  (display,  drawable,  gc ,  xf  y,  width,  height, 

anglel ,  angle2) 
Display  *display; 
Drawable  drawable ; 
GC  gc; 
int  xr  y; 

unsigned  int  width,  height; 
int  anglel,  angle2 ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenoi splay. 

drawa&le          Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

x  Specify  the  x  and  y  coordinates  of  the  upper-left  corner  of  the  rectangle  that 

y  contains  the  arc,  relative  to  the  origin  of  the  specified  drawable. 

width  Specify  the  width  and  height  in  pixels  of  the  major  and  minor  axes  of  the  arc. 

height 

anglel  Specifies  the  start  of  the  arc  relative  to  the  three-o'clock  position  from  the 

center.  Angles  are  specified  in  64ths  of  a  degree  (360  *  64  is  a  complete 
circle). 

angle2  Specifies  the  end  of  the  arc  relative  to  the  start  of  the  arc.  Angles  are  speci 

fied  in  64ths  of  a  degree  (360  *  64  is  a  complete  circle). 

Description 

XDrawArc  draws  a  circular  or  elliptical  arc.  An  arc  is  specified  by  a  rectangle  and  two  angles. 
The  x  and  y  coordinates  are  relative  to  the  origin  of  the  drawable,  and  define  the  upper-left  cor 
ner  of  the  rectangle.  The  center  of  the  circle  or  ellipse  is  the  center  of  the  rectangle,  and  the 
major  and  minor  axes  are  specified  by  the  width  and  height,  respectively.  The  angles  are 
signed  integers  in  64ths  of  a  degree,  with  positive  values  indicating  counterclockwise  motion 
and  negative  values  indicating  clockwise  motion,  truncated  to  a  maximum  of  360  degrees.  The 
start  of  the  arc  is  specified  by  anglel  relative  to  the  three-o'clock  position  from  the  center, 
and  the  path  and  extent  of  the  arc  is  specified  by  angle2  relative  to  the  start  of  the  arc. 

By  specifying  one  axis  to  be  zero,  a  horizontal  or  vertical  line  is  drawn  (inefficiently). 

Angles  are  computed  based  solely  on  the  coordinate  system  and  ignore  the  aspect  ratio.  In 
other  words,  if  the  bounding  rectangle  of  the  arc  is  not  square  and  anglel  is  zero  and 
angle2  is  (45x64),  a  point  drawn  from  the  center  of  the  bounding  box  through  the  endpoint 
of  the  arc  will  not  pass  through  the  corner  of  the  rectangle. 
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XDrawArc 


(continued) 


Xlib  -  Drawing  Primitives 


For  any  given  arc,  no  pixel  is  drawn  more  than  once,  even  if  angle2  is  greater  than  anglel 
by  more  than  360  degrees. 

XDrawArc  uses  these  graphics  context  components:  function,  plane_mask, 
line_width,  line_style,  cap_style,  join_style,  f ill_style,  subwindow_ 
mode,  clip_x_origin,  clip_y_origin,  and  clip_mask.  This  function  also  uses 
these  graphics  context  mode-dependent  components:  foreground,  background,  tile, 
stipple,  ts_x_origin,  ts_y_origin,  dash_of  f  set,  and  dash_list. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text, 


width 


6  o'clock 

Angle  =  270x64=17280 
Angle  =  -(  90x64 ) =5760 


12  o'clock 

(x,y)  —  v          Angle  =  90x64 

\        Angle  =  -  (270x64) 
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Example  1: 

Arc  from  A1  to  A2,  Counterclockwise 

A1  =  90  X  64 

A2  =  45  X  64 


Example  2: 

Arc  from  B1  to  B2,  Clockwise 

B1  =  270  X  64 

B2  =  -(45X64) 


Errors 

BadDrawable 

BadGC 

BadMatch 
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Xlib  -  Drawing  Primitives  (continued)  XDrawArc 

Related  Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw,  XDrawArcs, 
XDrawFilled,  XDrawLine, XDrawLines, XDrawPoint,  XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc,  XFillArcs,  XFill- 
Polygon, XFillRectangle,  XFillRectangles. 
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X 


•Xlib  -  Drawing  Primitives- 


Name 

XDrawArcs  —  draw  multiple  arcs. 

Synopsis 

XDrawArcs (  display,  drawable , 
Display  * display ; 
Drawable  drawable; 
GC  gc; 
XArc  *arcs; 
int  r>arcs; 


gc,  arcs,  narcs) 


Arguments 

di  spl ay 

drawable 

gc 

arcs 

narcs 


Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 
Specifies  the  drawable. 
Specifies  the  graphics  context. 
Specifies  a  pointer  to  an  array  of  arcs. 
Specifies  the  number  of  arcs  in  the  array. 


width 


6  o'clock 

Angle  =  270x64=17280 
Angle  =  -  (90x64)=5760 


Example  1 : 

Arc  from  A1  to  A2,  Counterclockwise 

A1  =  90  X  64 

A2  =  45  X  64 


12  o'clock 

(x,y)  —  v          Angle  =  90x64 
\        Angle  =  -(270x64) 

height 

9  o'clock 

Angle  =  180x64 
Angle  =  -(180x64) 


*^Jf  £2 

A1  ""'*--,, 

,•'' 

• 

^s"""*--  -—  -. 

81 

Center  of  bounding 
rectangle. 

3  o'clock 

Angle    =    0 


Example  2: 

Arc  from  81  to  B2,  Clockwise 

B1  =  270  X  64 

B2  =  -(45X64) 
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Xlib  -  Drawing  Primitives  (continued)  XDrawArcs 

Description 

This  is  the  plural  version  of  XDrawArc.  See  XDrawArc  for  details  of  drawing  a  single  arc. 

There  is  a  limit  to  the  number  of  arcs  that  can  be  drawn  in  a  single  call.  It  varies  according  to 
the  server.  To  determine  how  many  arcs  you  can  draw  in  a  single  call,  find  out  your  server's 
maximum  request  size  using  XMaxRequestSize.  Subtract  3  and  divide  by  three:  this  is  the 
maximum  number  of  arcs  you  can  draw  in  a  single  XDrawArcs  call. 

The  arcs  are  drawn  in  the  order  listed  in  the  arcs  array. 

By  specifying  one  axis  to  be  zero,  a  horizontal  or  vertical  line  can  be  drawn.  Angles  are  com 
puted  based  solely  on  the  coordinate  system,  ignoring  the  aspect  ratio. 

For  any  given  arc,  no  pixel  is  drawn  more  than  once.  If  the  last  point  in  one  arc  coincides  with 
the  first  point  in  the  following  arc,  the  two  arcs  will  join  correctly.  If  the  first  point  in  the  first 
arc  coincides  with  the  last  point  in  the  last  arc,  the  two  arcs  will  join  correctly.  If  two  arcs  join 
correctly  and  if  line_width  is  greater  than  0  and  the  arcs  intersect,  no  pixel  is  drawn  more 
than  once.  Otherwise,  the  intersecting  pixels  of  intersecting  arcs  are  drawn  multiple  times. 
Specifying  an  arc  with  one  endpoint  and  a  clockwise  extent  draws  the  same  pixels  as  specifying 
the  other  endpoint  and  an  equivalent  counterclockwise  extent,  except  as  it  affects  joins. 

XDrawArcs  uses  these  graphics  context  components:  function,  plane_mask, 
line_width,  line_style,  cap_style,  join_style,  fill_style,  subwindow_ 
mode,  clip_x_origin,  clip_y_origin,  and  clip_mask.  This  function  also  uses 
these  graphics  context  mode-dependent  components:  foreground,  background,  tile, 
stipple,  ts_x_origin,  ts_y_origin,  dash_of  f  set,  and  dash_list. 

The  following  is  a  technical  explanation  of  the  points  drawn  by  XDrawArcs.  For  an  arc  speci 
fied  as  [x,  y,  width,  height,  anglel,  angle2  ] ,  the  origin  of  the  major  and  minor  axes  is 
at  [x+  (width/2 ) ,  y+  (height  12 )  ] ,  and  the  infinitely  thin  path  describing  the  entire  circle 
or  ellipse  intersects  the  horizontal  axis  at  [x,  y+  (height /2)  ]  and  [x+width, 
y+ (height/2) ]  and  intersects  the  vertical  axis  at  [x+ (width/2)  ,y]  and 
[x+  (width/2) ,  y+height] .  These  coordinates  can  be  fractional.  That  is,  they  are  not 
truncated  to  discrete  coordinates.  The  path  should  be  defined  by  the  ideal  mathematical  path. 
For  a  wide  line  with  line  width  line_width,  the  bounding  outlines  for  filling  are  given  by 
the  infinitely  thin  paths  describing  the  arcs: 

[x+dx/2,    y+dy/2,    width-dx,    height-dy,    anglel,    angle2] 

and 

[x-line_width/2,  y-line_width/2,  width+line_width,  height+line_width, 
anglel,  angle2] 


where 


dx=min(line_width, width) 
dy=min(line  width, height) 
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If  (height  !  =  width)  the  angles  must  be  specified  in  the  effectively  skewed  coordinate 
system  of  the  ellipse  (for  a  circle,  the  angles  and  coordinate  systems  are  identical).  The  rela 
tionship  between  these  angles  and  angles  expressed  in  the  normal  coordinate  system  of  the 
screen  (as  measured  with  a  protractor)  is  as  follows: 

skewed-angle   =   atan (tan (normal-angle)    *   width/height)    +   adjust 

The  skewed-angle  and  normal-angle  are  expressed  in  radians  (rather  than  in  64ths  of  a  degree) 
in  the  range  [0,2*PI],  and  where  atan  returns  a  value  in  the  range  [-PI/2,  PI/2]  ,and 
where  adjust  is: 

0  for  normal-angle   in  the   range    [0,PI/2] 

PI  for   normal-angle    in   the   range    [PI/2,  (3*PI) /2] 

2*PI  for   normal-angle   in   the   range    [  (3*PI) /2, 2*PI] 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
Structures 

typedef   struct    { 

short   x,    y; 

unsigned  short  width,  height; 

short  anglel,  angle2;  /*   Start  and  end  of  arc,  in  */ 

/*   64ths  of  degrees  */ 
}  XArc; 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related  Commands 

XClearArea, XClearWindow,  XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, XDraw- 
Rectangle,  XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, XFill- 
Polygon, XFillRectangle,  XFillRectangles. 
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-Xlib  -  Drawing  Primmv.s /  XDrawFilted 

Name 

XDrawFilled  —  draw  a  filled  polygon  or  curve  from  vertex  list  (from  X10 ) . 

Synopsis 

Status  XDrawFilled (display,  drawable,  gc,  vlist,  vcount) 
Display  *display; 
Drawable  drawable ; 
GC  gc; 

Vertex  *vlist; 
int  vcount ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

dra wabl  e  Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

vl  i  s  t  Specifies  a  pointer  to  the  list  of  vertices. 

vcount  Specifies  how  many  vertices  are  in  v  1  i  s  t . 

Description 

This  function  is  provided  for  compatibility  with  X  Version  10.  To  use  it  you  must  include  the 
file  <XlllX10.h>  and  link  with  the  library  -loldX.  XDrawFilled  achieves  the  effects  of  the 
X  Version  10  XDrawTiled  and  XDrawFilled  functions. 

XDrawFilled  draws  arbitrary  polygons  or  curves,  according  to  the  same  rules  as  XDraw,  and 
then  fills  them. 

XDrawFilled  uses  the  following  graphics  context  components:  function,  plane_mask, 
line_width,  line_style,  cap_style,  join_style,  fill_style, 
subwindow_mode,  clip_x_origin,  clip_y_origin,  and  clip_mask.  This  function 
also  uses  these  graphics  context  mode-dependent  components:  foreground,  background, 
tile,  stipple,  ts_x_origin,  ts_y_origin,  dash_offset,  dash_list, 
f  ill_style  and  f  ill_rule. 

XDrawFilled  returns  a  Status  of  zero  on  failure,  and  nonzero  on  success. 
For  more  information,  see  Volume  One,  Appendix  B,X10  Compatibility. 

Related  Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawArcs, XDrawLine, XDrawLines, XDrawPoint,  XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs,  XFill- 
Polygon, XFillRectangle,  XFillRectangles. 
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•Xlib- Text- 


Name 

XDrawlmageString  —  draw  8-bit  image  text  characters. 

Synopsis 

XDrawlmageString ( display,  drawable ,  gc ,  x,  y,  string,  length) 
Display  *display; 
Drawable  drawable ; 
GC  gc; 
int  xf  y; 
char  *string; 
int  length; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

drawable         Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

x  Specify  the  x  and  y  coordinates  of  the  baseline  starting  position  for  the  image 

y  text  character,  relative  to  the  origin  of  the  specified  drawable. 

string  Specifies  the  character  string. 

length  Specifies  the  number  of  characters  in  the  s t  ri n g  argument. 

Description 

XDrawlmageString  draws  a  string,  but  unlike  XDrawString  it  draws  both  the  foreground 
and  the  background  of  the  characters.  It  draws  the  characters  in  the  foreground  and  fills  the 
bounding  box  with  the  background. 

XDrawlmageString  uses  these  graphics  context  components:  plane_mask,  fore 
ground,  background,  font,  subwindow_mode,  clip_x_origin,  clip_y_ 
origin,  and  clip_mask.  The  function  and  f ill_style  defined  in  gc  are  ignored; 
the  effective  function  is  GXcopy  and  the  effective  f  ill_style  is  FillSolid. 

XDrawlmageString  first  fills  a  destination  rectangle  with  the  background  pixel  defined 
in  gc,  and  then  paints  the  text  with  the  foreground  pixel.  The  upper-left  corner  of  the  filled 
rectangle  is  at  [x,  y  -  font_ascent],  the  width  is  overall->width  and  the  height  is 
ascent  +  descent,  where  overall->width,  ascent,  and  descent  are  as  would  be 
returned  by  XQueryTextExtents  using  gc  and  string. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Errors 

BadDrawable 

BadGC 

BadMatch 
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xiib  -  Text  (continued)  XDrawlmageString 

Related  Commands 

XDrawImageStringlS,  XDrawString,  XDrawStringl6,  XDrawText,  XDraw- 
Textl6, XQueryTextExtents, XQueryTextExtentsl6, XTextExtents,  XText- 
Extentsl6,XTextWidth,XTextWidthl6. 
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•Xlib-Text— 


Name 

XDrawImageStringl6  —  draw  16-bit  image  text  characters. 

Synopsis 

XDrawImageStringl 6 (display,  drawable,  gc ,  x,  y,  string,  length) 
Display  * display; 
Drawable  drawable; 
GC  gc; 
int  xr  y; 
XChar2b  *string; 
int  length; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawable         Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

x  Specify  the  x  and  y  coordinates  of  the  baseline  starting  position  for  the  image 

y  text  character,  relative  to  the  origin  of  the  specified  drawable. 

string  Specifies  the  character  string. 

length  Specifies  the  number  of  characters  in  the  string  argument. 

Description 

XDrawlmageStringl6  draws  a  string,  but  unlike  XDrawStringl6  it  draws  both  the  fore 
ground  and  the  background  of  the  characters.  It  draws  the  characters  in  the  foreground  and  fills 
the  bounding  box  with  the  background. 

XDrawlmageStringl6  uses  these  graphics  context  components:  plane_mask,  fore 
ground,  background,  font,  subwindow_mode,  clip_x_origin,  clip_y_ 
origin,  and  clip_mask.  The  function  and  f ill_style  defined  in  gc  are  ignored; 
the  effective  function  is  GXcopy  and  the  effective  f  ill_style  is  FillSolid. 

XDrawlmageStringlG  first  fills  a  destination  rectangle  with  the  background  pixel 
defined  in  gc,  and  then  paints  the  text  with  the  foreground  pixel.  The  upper-left  corner  of 
the  filled  rectangle  is  at  [x,  y  -  font_ascent],  the  width  is  overall->width  and  the 
height  is  ascent  +  descent,  where  overall->width,  ascent,  and  descent  are  as 
would  be  returned  by  XQueryTextExtentslG  using  gc  and  string. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Structures 

typedef  struct  { 

unsigned  char  bytel; 

unsigned  char  byte2; 
}  XChar2b; 
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-  Text  (continued)  XDrawlmageStringl  6 


Errors 

BadDrawable 

BadGC 

BadMatch 


Related  Commands 

XDrawImageString,XDrawString,XDrawStringl6,XDrawText,XDrawTextl6: 

XQueryTextExtents,XQueryTextExtentsl6,XTextExtents,XText- 

Extentsl6,XTextWidth,XTextWidthl6. 
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XDrawLine  \  _  Xllb  _  Drawlng  Pr|m|tives_ 

Name 

XDrawLine  —  draw  a  line  between  two  points. 

Synopsis 

XDrawLine  (  display,  drawable,  gc,  xl  ,  yl  ,  x2  ,  y2) 
Display  *  display; 
Drawable  dravrable; 
GC  gc; 
int  xl  r  yl  r  x2,  y2  ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

dra  wabl  e          Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

xl  Specify  the  coordinates  of  the  endpoints  of  the  line  relative  to  the  drawable 

yl  origin.  XLine  connects  point  (xl  ,  yl)  to  point  (x2,  y2). 

x2 


Description 

XDrawLine  uses  the  components  of  the  specified  graphics  context  to  draw  a  line  between  two 
points  in  the  specified  drawable.  No  pixel  is  drawn  more  than  once. 

XDrawLine  uses  these  graphics  context  components:  function,  plane_mask, 
line_width,  line_style,  cap_style,  fill_style,  subwindow_mode,  clip_ 
x_origin,  clip_y_origin,  and  clip_mask.  XDrawLine  also  uses  these  graphics  con 
text  mode-dependent  components:  foreground,  background,  tile,  stipple, 
ts_x_origin,  ts_y_origin,  dash_of  f  set,  and  dash_list. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Errors 

BadDrawable  Specified  drawable  is  invalid. 

BadGC  Specified  GC  is  invalid,  or  does  not  match  the  depth  of  drawable. 

BadMatch          Specified  drawable  is  an  inputOnly  window. 

Related  Commands 

XClearArea,  XClearWindow,  XCopyArea,  XCopyPlane,  XDraw,  XDrawArc, 
XDrawArcs,  XDrawFilled,  XDrawLines,  XDrawPoint,  XDrawPoints,  XDraw- 
Rectangle,  XDrawRectangles,  XDrawSegments,  XFillArc,  XFillArcs,  XFill- 
Polygon,  XFillRectangle,  XFillRectangles. 
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Name 

XDrawLines  —  draw  multiple  connected  lines. 

Synopsis 

XDrawLines  (  display,  drawable,  gc  ,  points,  npoints,  mode) 
Display  *display; 
Drawable  drawable; 
GC  gc; 

XPoint  *points; 
int  npoints; 
int  mode  ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawable  Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

point  s  Specifies  a  pointer  to  an  array  of  points. 

npoints  Specifies  the  number  of  points  in  the  array. 

mode  Specifies  the  coordinate  mode.  Pass  either  CoordModeOrigin  or  Coord- 

ModePrevious. 

Description 

XDrawLines  draws  a  series  of  lines  joined  end-to-end. 

It  draws  lines  connecting  each  point  in  the  list  (points  array)  to  the  next  point  in  the  list.  The 
lines  are  drawn  in  the  order  listed  in  the  points  array.  For  any  given  line,  no  pixel  is  drawn 
more  than  once.  If  thin  (zero  line  width)  lines  intersect,  pixels  will  be  drawn  multiple  times.  If 
the  first  and  last  points  coincide,  the  first  and  last  lines  will  join  correctly.  If  wide  lines  inter 
sect,  the  intersecting  pixels  are  drawn  only  once,  as  though  the  entire  multiline  request  were  a 
single  filled  shape. 

There  is  a  limit  to  the  number  of  lines  that  can  be  drawn  in  a  single  call,  that  varies  according  to 
the  server.  To  determine  how  many  lines  you  can  draw  in  a  single  call,  you  find  out  your 
server's  maximum  request  size  using  XMaxRequestSize.  Subtract  3  and  divide  by  two,  and 
this  is  the  maximum  number  of  lines  you  can  draw  in  a  single  XDrawLines  call. 

The  mode  argument  may  have  two  values: 

CoordModeOrigin  indicates  that  all  points  are  relative  to  the  drawable's  origin. 

•         CoordModePrevious  indicates  that  all  points  after  the  first  are  relative  to  the  previ 
ous  point.  (The  first  point  is  always  relative  to  the  drawable's  origin.) 

XDrawLines  uses  the  following  components  of  the  specified  graphics  context  to  draw  multi 
ple  connected  lines  in  the  specified  drawable:  function,  plane_mask,  line_width, 
line_style,  cap_style,  join_style,  fill_style,  subwindow_mode, 
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clip_x_origin,  clip_y_  origin,  and  clip_mask.  This  function  also  uses  these 
graphics  context  mode-dependent  components:  foreground,  background,  tile, 
stipple,  ts_x_origin,  ts_y_origin,  dash_of  f  set,  and  dash_list. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Structures 

typedef  struct  { 
short  x,  y; 
}  XPoint; 

Errors 

BadDrawable  Specified  drawable  is  invalid. 

BadGC  Specified  GC  is  invalid,  or  does  not  match  the  depth  of  drawable. 

BadMatch          Specified  drawable  is  an  InputOnly  window. 
BadValue          Invalid  coordinate_mode. 

Related  Commands 

XClearArea,  XClearWindow, XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawArcs, XDrawFilled,  XDrawLine, XDrawPoint, XDrawPoints, XDraw- 
Rectangle,  XDrawRectangles, XDrawSegments, XFillArc,  XFillArcs,  XFill- 
Polygon, XFillRectangle,  XFillRectangles. 
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Name 

XDrawPoint  —  draw  a  point. 

Synopsis 

XDrawPoint ( display,  drawable,  gc ,  xr  y) 
Display  *display; 
Drawable  drawable; 
GC  gc; 
int  xr  y; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawable         Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

x  Specify  the  x  and  y  coordinates  of  the  point,  relative  to  the  origin  of  the  draw- 

y  able. 

Description 

XDrawPoint  draws  a  single  point  into  the  specified  drawable.  XDrawPoint  uses  these 
graphics  context  components:  function,  plane_mask,  foreground,  subwin- 
dow_mode,  clip_x_origin,  clip_y_origin,  and  clip_mask.  Use  XDrawPoints 
to  draw  multiple  points. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related  Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawArcs, XDrawFilled,  XDrawLine, XDrawLines, XDrawPoints, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs,  XFill- 
Polygon, XFillRectangle,  XFillRectangles. 
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Name 

XDrawPoints  —  draw  multiple  points. 

Synopsis 

XDrawPoints ( display,  drawable,  gc ,  points,  npoints,  mode) 
Display  ^display; 
Drawable  drawable; 
GC  gc; 

XPoint  *points; 
int  npoints; 
int  mode ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

dra  wabl  e         Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

points  Specifies  a  pointer  to  an  array  of  XPoint  structures  containing  the  positions 

of  the  points. 

npoints  Specifies  the  number  of  points  to  be  drawn. 

mode  Specifies  the  coordinate  mode.  CoordModeOrigin  treats  all  coordinates  as 

relative  to  the  origin,  while  CoordModePrevious  treats  all  coordinates 
after  the  first  as  relative  to  the  previous  point,  while  the  first  is  still  relative  to 
the  origin. 

Description 

XDrawPoints  draws  one  or  more  points  into  the  specified  drawable. 

There  is  a  limit  to  the  number  of  points  that  can  be  drawn  in  a  single  call,  that  varies  according 
to  the  server.  To  determine  how  many  points  you  can  draw  in  a  single  call,  you  find  out  your 
server's  maximum  request  size  using  XMaxRequestSize.  Subtract  3  and  this  is  the  maxi 
mum  number  of  points  you  can  draw  in  a  single  XDrawPoints  call. 

XDrawPoints  uses  these  graphics  context  components:  function,  plane_mask,  fore 
ground,  subwindow_mode,  clip_x_origin,  clip_y_origin,  and  clip_mask. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Structures 

typedef  struct  { 
short  x,  y; 
}  XPoint; 
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Errors 

BadDrawable 
BadGC 
BadMatch 
BadValue 

Related  Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawArcs, XDrawFilled,  XDrawLine, XDrawLines, XDrawPointS, XDraw- 
Rectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs,  XFill- 
Polygon, XFillRectangle, XFillRectangles. 
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Name 

XDrawRectangle  —  draw  an  outline  of  a  rectangle. 

Synopsis 

XDrawRectangle  (display,  drawable,  gc,  x,  y,  width,  height) 
Display  * display; 
Drawable  drawable; 
GC  gc; 
int  x r  y; 
unsigned  int  width,  height; 


Arguments 

di  spl ay 

drawable 

gc 

x 

y 

width 
height 


Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 
Specifies  the  drawable. 
Specifies  the  graphics  context. 

Specify  the  x  and  y  coordinates  of  the  upper-left  corner  of  the  rectangle,  rela 
tive  to  the  drawable's  origin. 

Specify  the  width  and  height  in  pixels.  These  dimensions  define  the  outline 
of  the  rectangle. 


20  pixels 


20  pixels 


Description 

XDrawRectangle  draws  the  outline  of  the  rectangle  by  using  the  x  and  y  coordinates, 
width  and  height,  and  graphics  context  you  specify.  Specifically,  XDrawRectangle  uses 
these  graphics  context  components:  function,  plane_mask,  line_width, 
line_style,  cap_style,  join_style,  fill_style,  subwindow_mode,  clip_ 
x_origin,  clip_y_origin,  and  clip_mask.  This  function  also  uses  these  graphics  con 
text  mode-dependent  components:  foreground,  background,  tile,  stipple, 
ts_x_origin,  ts_y_origin,  dash_of  f  set,  and  dash_list. 

For  the  specified  rectangle,  no  pixel  is  drawn  more  than  once. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 
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Structure 

typedef   struct    { 

short   x,    y; 

unsigned  short  width,  height; 
}  XRectangle; 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related  Commands 

XClearArea,  XClearWindow, XCopyArea, XCopyPlane, XDraw, XDrawArc, 
XDrawArcs, XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangles, XDrawSegments, XFillArc,  XFillArcs,  XFillPolygon, 
XFillRectangle, XFillRectangles. 
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Name 

XDrawRectangles  —  draw  the  outlines  of  multiple  rectangles. 

Synopsis 

XDrawRectangles (display,  drawable,  gc ,  rectangles,  nrectangles) 
Display  *display; 
Drawable  drawa&le; 
GC  gc; 

XRectangle  rectangles []  ; 
int  nrectangles; 

Arguments 

di  spl ay  Specifies  a  connection  to  an  X  server;  returned  from  xopenD isplay. 

dra  wabl  e         Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

rectangles     Specifies  a  pointer  to  an  array  of  rectangles  containing  position  and  size 
information. 

nrectangles  Specifies  the  number  of  rectangles  in  the  array. 

20  pixels 


Description 

XDrawRectangles  draws  the  outlines  of  the  specified  rectangles  by  using  the  position  and 
size  values  in  the  array  of  rectangles.  The  x  and  y  coordinates  of  each  rectangle  are  relative  to 
the  drawable's  origin,  and  define  the  upper-left  corner  of  the  rectangle. 

The  rectangles  are  drawn  in  the  order  listed.  For  any  given  rectangle,  no  pixel  is  drawn  more 
than  once.  If  rectangles  intersect,  pixels  are  drawn  multiple  times. 

There  is  a  limit  to  the  number  of  rectangles  that  can  be  drawn  in  a  single  call.  It  varies  accord 
ing  to  the  server.  To  determine  how  many  rectangles  you  can  draw  in  a  single  call,  find  out 
your  server's  maximum  request  size  using  XMaxRequestSize.  Subtract  3  and  divide  by 
two.  This  is  the  maximum  number  of  rectangles  you  can  draw  in  a  single  XDraw 
Rectangles  call. 

This  function  uses  these  graphics  context  components:  function,  plane_mask, 
line_width,  line_style,  cap_style,  join_style,  fill_style,  subwin- 
dow_mode,  clip_x_origin,  clip_y_origin,  and  clip_mask.  XDrawRectangles 
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also  uses  these  graphics  context  mode-dependent  components:  foreground,  background, 
tile,  stipple,  ts_x_origin,  ts_y_origin,  dash_of  f  set,  and  dash_list. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Structures 

typedef   struct    { 

short   x,    y; 

unsigned  short  width,  height; 
}  XRectangle; 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related  Commands 

XClearArea,  XClearWindow, XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawArcs, XDrawFilled,  XDrawLine, XDrawLines, XDrawPoint,  XDrawPoints, 
XDrawRectangle,  XDrawSegments, XFillArc,  XFillArcs,  XFillPolygon, 
XFillRectangle,  XFillRectangles. 
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Name 

XDrawSegments  —  draw  multiple  disjoint  lines. 

Synopsis 

XDrawSegments ( display,  drawable,  gc,  segments,  nsegments) 
Display  *display; 
Drawable  drawable; 
GC  gc; 

XSegment  * segments; 
int  nsegments; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawable  Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

segments  Specifies  a  pointer  to  an  array  of  line  segments. 

nse gmen  ts  Specifies  the  number  of  segments  in  the  array. 

Description 

XDrawSegments  draws  multiple  line  segments  into  the  specified  drawable.  Each  line  is 
specified  by  a  pair  of  points,  so  the  line  may  be  connected  or  disjoint. 

For  each  segment,  XDrawSegments  draws  a  line  between  (xl,  yl)  and  (x2,  y2).  The 
lines  are  drawn  in  the  order  listed  in  segments.  For  any  given  line,  no  pixel  is  drawn  more 
than  once.  If  lines  intersect,  pixels  will  be  drawn  multiple  times.  The  lines  will  be  drawn  sepa 
rately,  without  regard  to  the  join_style. 

There  is  a  limit  to  the  number  of  segments  that  can  be  drawn  in  a  single  call.  It  varies  accord 
ing  to  the  server.  To  determine  how  many  segments  you  can  draw  in  a  single  call,  find  out  your 
server's  maximum  request  size  using  XMaxRequestSize.  Subtract  3  and  divide  by  two. 
This  is  the  maximum  number  of  segments  you  can  draw  in  a  single  XDrawSegments  call. 

XDrawSegments  uses  these  graphics  context  components:  function,  plane_mask, 
line_width,  line_style,  cap_style,  fill_style,  subwindow__mode,  clip_ 
x_origin,  clip_y_origin,  and  clip_mask.  XDrawSegments  also  uses  these  graph 
ics  context  mode-dependent  components:  foreground,  background,  tile,  stipple, 
ts_x_origin,  ts_y_origin,  dash_of  f  set,  and  dash_list. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Structures 

typedef  struct  { 

short  xl,  yl,  x2,  y2; 
}  XSegment; 
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Errors 

BadDrawable  Specified  drawable  is  invalid. 

BadGC  Specified  GC  is  invalid,  or  does  not  match  the  depth  of  drawable. 

BadMatch          Specified  drawable  is  an  InputOnly  window. 

Related  Commands 

XClearArea,  XClearWindow, XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawArcs,  XDrawFilled, XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle, XDrawRectangles, XFillArc,  XFillArcs,  XFillPolygon, 
XFillRectangle, XFillRectangles. 
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Name 

XDrawString  —  draw  an  8-bit  text  string,  foreground  only. 

Synopsis 

XDrawString  ( display,  drawable ,  gc ,  x,  y,  string,  length) 
Display  *display; 
Drawable  drawable ; 
GC  gc; 
int  x,  y; 
char  *string; 
int  length; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

dr a  wai>l  e          Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

x  Specify  the  x  and  y  coordinates  of  the  baseline  starting  position  for  the  char- 

y  acter,  relative  to  the  origin  of  the  specified  drawable. 

string  Specifies  the  character  string. 

length  Specifies  the  number  of  characters  in  s t  ri n g. 

Description 

XDrawString  draws  the  given  string  into  a  drawable  using  the  foreground  only  to  draw 
set  bits  in  the  font.  It  does  not  affect  any  other  pixels  in  the  bounding  box  for  each  character. 

The  y  coordinate  defines  the  baseline  row  of  pixels  while  the  x  coordinate  is  the  point  from 
which  Ibearing,  rbearing,  and  width  are  measured. 

XDrawString  uses  these  graphics  context  components:  function,  plane_mask, 
fill_style,  font,  subwindow_mode,  clip_x_origin,  clip_y_origin,  and 
clip_mask.  This  function  also  uses  these  graphics  context  mode-dependent  components: 
foreground,  tile,  stipple,  ts_x_origin,  and  ts_y_origin.  Each  character 
image,  as  defined  by  the  font  in  gc,  is  treated  as  an  additional  mask  for  a  fill  operation  on  the 
drawable. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Errors 

BadDrawable 
BadFont 
BadGC 
BadMatch 
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Related  Commands 

XDrawImageString, XDrawImageStringl6,  XDrawStringl6,  XDrawText, 
XDrawTextl6, XQueryTextExtents, XQueryTextExtentslG, XTextExtents, 
XTextExtentsl6, XTextWidth, XTextWidthlG. 
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Name 

XDrawStringl 6  —  draw  two-byte  text  strings. 

Synopsis 

XDrawStringl 6 (display,  drawable,  gc ,  x,  yf  string,  length) 
Display  * display; 
Drawable  drawable; 
GC  gc  ; 
int  x,  y; 
XChar2b  *string; 
int  length; 

Arguments 

di  splay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

draw-able          Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

x  Specify  the  x  and  y  coordinates  of  the  baseline  starting  position  for  the  char- 

y  acter,  relative  to  the  origin  of  the  specified  drawable. 

string  Specifies  the  character  string.  Characters  are  two  bytes  wide. 

length  Specifies  the  number  of  characters  in  string. 

Description 

XDrawStringl 6  draws  a  string  in  the  foreground  pixel  value  without  drawing  the  surround 
ing  pixels. 

The  y  coordinate  defines  the  baseline  row  of  pixels  while  the  x  coordinate  is  the  point  from 
which  Ibearing,  rbearing,  and  width  are  measured.  For  more  information  on  text 
placement,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

XDrawStringl 6  uses  these  graphics  context  components:  function,  plane_mask, 
fill_style,  font,  subwindow_mode,  clip_x_origin,  clip_y_origin,  and 
clip_mask.  This  function  also  uses  these  graphics  context  mode-dependent  components: 
foreground,  tile,  stipple,  ts_x_origin,  and  ts_y_origin.  Each  character 
image,  as  defined  by  the  font  in  gc,  is  treated  as  an  additional  mask  for  a  fill  operation  on  the 
drawable. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Structures 

typedef  struct  { 

unsigned  char  bytel; 

unsigned  char  byte2; 
}  XChar2b; 
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Errors 

BadDrawable 
BadFont 
BadGC 
BadMatch 

Related  Commands 

XDrawImageString, XDrawImageStringlG, XDrawString, XDrawText, XDraw- 
Textl6,XQueryTextExtents,XQueryTextExtentsl6,XTextExtents,XText- 
Extentsl6,XTextWidth,  XTextWidthl6. 
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Name 

XDrawText  —  draw  8-bit  polytext  strings. 

Synopsis 

XDrawText ( display,  drawable,  gc ,  x,  y,  Items,  nltems) 
Display  *dlsplay; 
Drawable  drawable; 
GC  gc ; 
int  x,  y; 
XTextltem  * Items; 
int  nltems; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawable         Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

x  Specify  the  x  and  y  coordinates  of  the  baseline  starting  position  for  the  initial 

y  string,  relative  to  the  origin  of  the  specified  drawable. 

i  t  ems  Specifies  a  pointer  to  an  array  of  text  items. 

nl  terns  Specifies  the  number  of  text  items  in  the  Items  array. 

Description 

XDrawText  is  capable  of  drawing  multiple  strings  on  the  same  horizontal  line  and  changing 
fonts  between  strings.  Each  XTextltem  structure  contains  a  string,  the  number  of  characters 
in  the  string,  the  delta  offset  from  the  starting  position  for  the  string,  and  the  font.  Each  text 
item  is  processed  in  turn.  The  font  in  each  XTextltem  is  stored  in  the  specified  GC  and  used 
for  subsequent  text.  If  the  XTextltem.  font  is  None,  the  font  in  the  GC  is  used  for  drawing 
and  is  not  changed.  Switching  between  fonts  with  different  drawing  directions  is  permitted. 

The  delta  in  each  XTextltem  specifies  the  change  in  horizontal  position  before  the  string  is 
drawn.  The  delta  is  always  added  to  the  character  origin  and  is  not  dependent  on  the  draw 
direction  of  the  font.  For  example,  if  x  =  40,  y  =  20,  and  items  [0]  .delta  =  8,  the 
string  specified  by  items  [0]  .chars  would  be  drawn  starting  at  x  =  48,  y  =  20.  The 
delta  for  the  second  string  begins  at  the  rbearing  of  the  last  character  in  the  first  string.  A 
negative  delta  would  tend  to  overlay  subsequent  strings  on  the  end  of  the  previous  string. 

Only  the  pixels  selected  in  the  font  are  drawn  (the  background  member  of  the  GC  is  not  used 
to  fill  the  bounding  box). 

There  is  a  limit  to  the  number  and  size  of  strings  that  can  be  drawn  in  a  single  call,  that  varies 
according  to  the  server.  To  determine  how  much  text  you  can  draw  in  a  single  call,  you  find  out 
your  server's  maximum  request  size  using  XMaxRequestSize.  Subtract  four,  and  then  sub 
tract  (  (strlen  (string)  +2)  /  4)  for  each  string.  This  is  the  maximum  amount  of 
text  you  can  draw  in  a  single  XDrawText  call. 
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Xlib-Text  (continued)  XDrawText 

XDrawText  uses  the  following  elements  in  the  specified  GC:  function,  plane_mask, 
fill_style,  font,  subwindow_mode,  clip_x_origin,  clip_y_origin,  and 
clip_mask.  This  function  also  uses  these  graphics  context  mode-dependent  components: 
foreground,  tile,  stipple,  ts_x_origin,  and  ts_y_origin. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Structures 

typedef  struct  { 

char  *chars;  /*  pointer  to  string  */ 

int  nchars;  /*  number  of  characters  */ 

int  delta;  /*  delta  between  strings  */ 

Font  font;  /*  font  to  print  it  in,  None  don't  change  */ 

}  XTextltem; 

Errors 

BadDrawable 
BadFont 
BadGC 
BadMatch 

Related  Commands 

XDrawImageString, XDrawImageStringl6, XDrawString,  XDrawStringlS, 
XDrawTextlS,  XQueryTextExtents, XQueryTextExtentslS, XTextExtents, 
XTextExtentsl6, XTextWidth, XTextWidthlG. 
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XDrawText16  \ X|ib  Tex(_ 

Name 

XDrawTextl6  —  draw  16-bit  poly  text  strings. 

Synopsis 

XD r a wTextlS ( display,  drawable,  gc,  x,  y,  items,  nitems) 
Display  * display ; 
Drawable  drawable; 
GC  gc; 
int  xr  y; 

XTextIteml6  * items; 
int  nitems; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

drawable         Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

x  Specify  the  x  and  y  coordinates  of  the  baseline  starting  position  for  the  initial 

y  string,  relative  to  the  origin  of  the  specified  drawable. 

items  Specifies  a  pointer  to  an  array  of  text  items  using  two-byte  characters, 

nit  ems  Specifies  the  number  of  text  items  in  the  array. 

Description 

XDrawTextlG  is  capable  of  drawing  multiple  strings  on  the  same  horizontal  line  and  chang 
ing  fonts  between  strings.  Each  XTextltem  structure  contains  a  string,  the  number  of  charac 
ters  in  the  string,  the  delta  offset  from  the  starting  position  for  the  string,  and  the  font.  Each 
text  item  is  processed  in  turn.  The  font  in  each  XTextltem  is  stored  in  the  specified  GC  and 
used  for  subsequent  text.  If  the  XTextIteml6  .  font  is  None,  the  font  in  the  GC  is  used  for 
drawing  and  is  not  changed.  Switching  between  fonts  with  different  drawing  directions  is  per 
mitted. 

The  delta  in  each  XTextltem  specifies  the  change  in  horizontal  position  before  the  string  is 
drawn.  The  delta  is  always  added  to  the  character  origin  and  is  not  dependent  on  the  drawing 
direction  of  the  font.  For  example,  if  x  =  40,y  =  20,  and  items  [0]  .delta  =  8,  the 
string  specified  by  items  [0]  .chars  would  be  drawn  starting  at  x  =  48,  y  =  20.  The 
delta  for  the  second  string  begins  at  the  rbearing  of  the  last  character  in  the  first  string.  A 
negative  delta  would  tend  to  overlay  subsequent  strings  on  the  end  of  the  previous  string. 

Only  the  pixels  selected  in  the  font  are  drawn  (the  background  member  of  the  GC  is  not  used 
to  fill  the  bounding  box). 

There  is  a  limit  to  the  number  and  size  of  strings  that  can  be  drawn  in  a  single  call,  that  varies 
according  to  the  server.  To  determine  how  much  text  you  can  draw  in  a  single  call,  you  find  out 
your  server's  maximum  request  size  using  XMaxRequestSize.  Subtract  four,  and  then  sub 
tract  (  (strlen  (string)  +2)  /  4)  for  each  string.  This  is  the  maximum  amount  of 
text  you  can  draw  in  a  single  XDrawText  1 6  call. 
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Xlib  -  Text 


(continued) 


XDrawText16 


XDrawText  16  uses  the  following  elements  in  the  specified  GC:  function,  plane_mask, 
fill_style,  font,  subwindow_mode,  clip_x_origin,  clip_y_origin,  and 
clip_mask.  This  function  also  uses  these  graphics  context  mode-dependent  components: 
foreground,  tile,  stipple,  ts_x_origin,  and  ts_y_origin. 

Note  that  the  chars  member  of  the  XText  Iteml  6  structure  is  of  type  XChar2b,  rather  than 
of  type  char  as  it  is  in  the  XText  Item  structure.  For  fonts  defined  with  linear  indexing 
rather  than  two-byte  matrix  indexing,  the  X  server  will  interpret  each  member  of  the  XChar2b 
structure  as  a  16-bit  number  that  has  been  transmitted  most  significant  byte  first.  In  other 
words,  the  bytel  member  of  the  XChar2b  structure  is  taken  as  the  most  significant  byte. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 


/*  2  byte  characters  */ 

/*  number  of  characters  */ 

/*  delta  between  strings  */ 

/*  font  to  print  it  in,  None  don't  change 


/*  normal  16  bit  characters  are  two  bytes  */ 


Structures 

typedef  struct  { 

XChar2b  *chars; 
int  nchars; 
int  delta; 

Font  font; 
}  XTextltemlG; 

typedef  struct  { 

unsigned  char  bytel; 

unsigned  char  byte2; 
}  XChar2b; 

Errors 

BadDrawable 
BadFont 
BadGC 
BadMatch 


Related  Commands 

XDrawImageString, XDrawImageStringl6, XDrawString, XDrawStringl6, 
XDrawText, XQueryTextExtents, XQueryTextExtentsl6, XTextExtents, 
XTextExtentslG, XTextWidth,  XTextWidthl6. 
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XEmptyRegion  \ 


-Xlib-  Regions- 


Name 

XEmptyRegion  —  determine  if  a  region  is  empty. 

Synopsis 

Bool   XEmptyRegion ( r) 
Region   r; 

Arguments 

r  Specifies  the  region  to  be  checked. 

Description 

XEmptyRegion  will  return  True  if  the  specified  region  is  empty,  or  False  otherwise. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion, XDestroyRegion, XEqualRegion,  Xlntersect- 
Region, XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, 
XSetRegion, XShrinkRegion,  XSubtractRegion,  XUnionRectWithRegion, 
XUnionRegion,  XXorRegion. 
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-x,,b  -  HO,«  Access /  XEnableAccessControl 

Name 

XEnableAccessControl  —  use  access  control  list  to  allow  or  deny  connection  requests. 

Synopsis 

XEnableAccessControl (display) 
Display  * display ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

Description 

XEnableAccessControl  instructs  the  server  to  use  the  host  access  list  to  determine 
whether  access  should  be  granted  to  clients  seeking  a  connection  with  the  server. 

By  default,  the  host  access  list  is  used.  If  access  has  not  been  disabled  with  XDisable- 
AccessControl  or  XSetAccessControl,  this  routine  does  nothing. 

This  routine  can  only  be  called  by  clients  running  on  the  same  host  as  the  server. 
For  more  information,  see  Volume  One,  Chapter  13,  Other  Programming  Techniques. 

Errors 

BadAccess 

Related  Commands 

XAddHost, XAddHosts,  XDisableAccessControl, XListHosts,  XRemoveHost, 
XRemoveHosts, XSetAccessControl. 
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XEqualRegion 

Xlib  -  Regions- 
Name 

XEqualRegion  —  determine  if  two  regions  have  the  same  size,  offset,  and  shape. 

Synopsis 

Bool  XEqualRegion  (rl,  r2) 
Region  rl ,  r2 ; 

Arguments 

rl  Specify  the  two  regions  you  want  to  compare. 

r2 

Description 

XEqualRegion  returns  True  if  the  two  regions  are  identical;  i.e.,  they  have  the  same  offset, 
size  and  shape,  or  False  otherwise. 

Regions  are  located  using  an  offset  from  a  point  (the  region  origin)  which  is  common  to  all 
regions.  It  is  up  to  the  application  to  interpret  the  location  of  the  region  relative  to  a  drawable. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion, XDestroyRegion, XEmptyRegion,  Xlntersect- 
Region, XOf f setRegion, XPointlnRegion,  XPolygonRegion,  XRectlnRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion,  XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 
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-Xlib  -  Resource  Manager / 

Name 

XEventsQueued  —  check  the  number  of  events  in  the  event  queue. 

Synopsis 

int  XEventsQueued (  display,  mode) 
Display  *  display; 
int  mode ; 

Arguments 

display  Specifies  a  connection  to  a  Display  structure,  returned  from  XOpen- 

Display. 

mode  Specifies  whether  the  request  buffer  is  flushed  if  there  are  no  events  in  Xlib's 

queue.     You    can    specify    one   of  these    constants:     QueuedAl ready, 
QueuedAfterFlush,  QueuedAfterReading. 

Description 

XEventsQueued  checks  whether  events  are  queued.  If  there  are  events  in  Xlib's  queue,  the 
routine  returns  immediately  to  the  calling  routine.  Its  return  value  is  the  number  of  events 
regardless  of  mode. 

mode  specifies  what  happens  if  no  events  are  found  on  Xlib's  queue. 

•  If  mode  is  QueuedAlready,  and  there  are  no  events  in  the  queue,  XEvents 
Queued  returns  zero  (it  does  not  flush  the  request  buffer  or  attempt  to  read  more 
events  from  the  connection). 

•  If  mode  is  QueuedAfterFlush,  and  there  are  no  events  in  the  queue,  XEvents 
Queued  flushes  the  request  buffer,  attempts  to  read  more  events  out  of  the  applica 
tion's  connection,  and  returns  the  number  read. 

If  mode  is  QueuedAfterReading,  and  there  are  no  events  in  the  queue, 
XEventsQueued  attempts  to  read  more  events  out  of  the  application's  connection 
without  flushing  the  request  buffer  and  returns  the  number  read. 

Note  that  XEventsQueued  always  returns  immediately  without  I/O  if  there  are  events 
already  in  the  queue. 

XEventsQueued  with  mode  QueuedAfterFlush  is  identical  in  behavior  to  XPending. 
XEventsQueued  with  mode  QueuedAlready  is  identical  to  the  QLength  macro  (see 
Appendix  C,  Macros). 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event,  XCheckTypedWindowEvent, XCheckWindowEvent,  XGetlnputFocus, 
XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, XPeekEvent, XPeek- 
If Event,  XPending,  XPutBackEvent, XSelectlnput, XSendEvent, XSetlnput- 
Focus, XSynchronize, XWindowEvent. 
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XFetchBuffer  "\ 


•Xlib -Cut  Buffers— 


Name 

XFetchBuffer  —  return  data  from  a  cut  buffer. 

Synopsis 

char    *XFetchBuffer (display,  nbytes ,    buffer) 
Display   *  display ; 

int    *  nbytes;  /*  RETURN    */ 
int   buffer; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

nbytes  Returns  the  number  of  bytes  in  buffer  returned  by  XFetchBuffer.  If 

there  is  no  data  in  the  buffer,  *  nbytes  is  set  to  0. 

buffer  Specifies  which  buffer  you  want  data  from.  Specify  an  integer  from  0  to  7 

inclusive. 

Description 

XFetchBuffer  returns  data  from  one  of  the  8  buffers  provided  for  interclient  communica 
tion.  If  the  buffer  contains  data,  XFetchBuffer  returns  the  number  of  bytes  in  nbytes, 
otherwise  it  returns  NULL  and  sets  *nbytes  to  0.  The  appropriate  amount  of  storage  is  allo 
cated  and  the  pointer  returned;  the  client  must  free  this  storage  when  finished  with  it  by  calling 
XFree.  Note  that  the  cut  buffer  does  not  necessarily  contain  text,  so  it  may  contain  embedded 
null  bytes  and  may  not  terminate  with  a  null  byte. 

Selections  are  preferred  over  cut  buffers  as  a  communication  scheme. 

For  more  information  on  cut  buffers,  see  Volume  One,  Chapter  13,  Other  Programming  Tech 
niques. 

Errors 

BadValue          buffer  not  an  integer  between  0  and  7  inclusive. 

Related  Commands 

XFetchBytes, XRotateBuf f ers, XStoreBuf f er,  XStoreBytes. 


1 78  Xlib  Reference  Manual 


—Xlib -Cut  Buffers- 


J  XFetch  Bytes 


Name 

XFetchBytes  —  return  data  from  cut  buffer  0. 

Synopsis 

char  *XFetchBytes ( display,  nbytes) 
Display  ^display; 
int  *  nbytes;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

nbytes  Returns  the  number  of  bytes  in  the  string  returned  by  XFetchBytes.  If 

there  is  no  data  in  the  buffer,  *  nbytes  is  set  to  0. 

Description 

XFetchBytes  returns  data  from  cut  buffer  0  of  the  8  buffers  provided  for  interclient  commu 
nication.  If  the  buffer  contains  data,  XFetchBytes  returns  the  number  of  bytes  in  nbytes, 
otherwise  it  returns  NULL  and  sets  *  nbytes  to  0.  The  appropriate  amount  of  storage  is  allo 
cated  and  the  pointer  returned;  the  client  must  free  this  storage  when  finished  with  it  by  calling 
XFree.  Note  that  the  cut  buffer  does  not  necessarily  contain  text,  so  it  may  contain  embedded 
null  bytes  and  may  not  terminate  with  a  null  byte. 

Use  XFetchBuf  f  er  to  fetch  data  from  any  specified  cut  buffer. 
Selections  are  preferred  over  cut  buffers  as  a  communication  method. 

For  more  information  on  cut  buffers,  see  Volume  One,  Chapter  13,  Other  Programming  Tech 
niques. 

Related  Commands 

XFetchBuf fer, XRotateBuf f ers, XStoreBuf f er,  XStoreBytes. 
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XFetChName  V xm>-W.ndow  Manager  Hints- 

Name 

XFetchName  —  get  a  window's  name  (XA_WM_NAME  property). 

Synopsis 

Status  XFetchName  ( display,  w,  window_name) 
Display  *  display; 
Window  w; 
char  **window_name;        /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

w  Specifies  the  ID  of  the  window  whose  name  you  want  a  pointer  set  to. 

window_name  Returns  a  pointer  to  the  window  name,  which  will  be  a  null-terminated  string. 
If  the  XA_WM_NAME  property  has  not  been  set  for  this  window,  XFetchName 
sets  windowname  to  NULL.  When  finished  with  it,  a  client  can  free  the  name 
string  using  XFree. 

Description 

XFetchName  is  superseded  by  XGetWMName  in  Release  4.  XFetchName  returns  the  current 
value  of  the  XA_WM_NAME  property  for  the  specified  window.  XFetchName  returns  nonzero  if 
it  succeeds,  and  zero  if  the  property  has  not  been  set  for  the  argument  window. 

For  more  information,  see  Volume  One,  Chapter  10,  Interdient  Communication,  and  Chapter 
14,  Window  Management. 

Errors 

BadWindow 

Related  Commands 

XGetClassHint, XGetlconName, XGetlconSizes,  XGetNormalHints, XGet- 
SizeHints, XGetTransientForHint, XGetWMHints,  XGetZoomHints,  XSet- 
ClassHint, XSetCommand, XSetlconName,  XSetlconSizes,  XSetNormalHints, 
XSetSizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, 
XStoreName. 
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-Xllb  -  Drawing  Primitives '  XFlll  Arc 

Name 

XFillArc  —  fill  an  arc. 

Synopsis 

XFillArc  (display,  draw-able,  gc ,   x,  y,  width,  height, 

anglel ,  angle2) 
Display  * display ; 
Drawable  drawable; 
GC  gc; 
int  x ,  y  ; 

unsigned  int  width,  height; 
int  anglel,  angle2 ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

dra  wabl  e          Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

x  Specify  the  x  and  y  coordinates  of  the  upper-left  corner  of  the  bounding  box 

y  containing  the  arc,  relative  to  the  origin  of  the  drawable. 

width  Specify  the  width  and  height  in  pixels.  These  are  the  major  and  minor  axes  of 

height  the  arc. 

anglel  Specifies  the  start  of  the  arc  relative  to  the  three-o'clock  position  from  the 

center.  Angles  are  specified  in  64ths  of  degrees. 

angle 2  Specifies  the  path  and  extent  of  the  arc  relative  to  the  start  of  the  arc.  Angles 

are  specified  in  64ths  of  degrees. 

Description 

XFillArc  draws  a  filled  arc.  The  x,  y,  width,  and  height  arguments  specify  the  bounding 
box  for  the  arc.  See  XDrawArc  for  the  description  of  how  this  bounding  box  is  used  to  com 
pute  the  arc.  Some,  but  not  all,  of  the  pixels  drawn  with  XDrawArc  will  be  drawn  by  XFill 
Arc  with  the  same  arguments.  See  XFillRectangle  for  an  example  of  the  differences  in 
pixels  drawn  by  the  draw  and  fill  routines. 

The  arc  forms  one  boundary  of  the  area  to  be  filled.  The  other  boundary  is  determined  by  the 
arc_mode  in  the  GC.  If  the  arc_mode  in  the  GC  is  ArcChord,  the  single  line  segment 
joining  the  endpoints  of  the  arc  is  used.  If  ArcPieSlice,  the  two  line  segments  joining  the 
endpoints  of  the  arc  with  the  center  point  are  used. 

XFillArc  uses  these  graphics  context  components:  function,  plane_mask, 
f  ill_style,  arc_mode,  subwindow_mode,  clip_x_origin,  clip_y_origin,  and 
clip_mask.  This  function  also  uses  these  graphics  context  mode-dependent  components: 
foreground,  background,  tile,  stipple,  ts_x_origin,  and  ts_y_  origin. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 
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XFIIIArc  (continued)  Xlib  -  Drawing  Primitives 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related  Commands 

XClearArea,  XClearWindow,  XCopyArea,  XCopyPlane,  XDraw,  XDrawArc, 
XDrawArcs, XDrawFilled,  XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle,  XDrawRectangles, XDrawSegments, XFillArcs, XFill- 
Polygon,  XFillRectangle, XFillRectangles. 


Xlib  Reference  Manual 


-Xlib  -  Drawing  Primitives '  XFIIIArCS 

Name 

XFillArcs  —  fill  multiple  arcs. 

Synopsis 

XFillArcs ( display,  drawable ,  gc ,  arcs,  narcs) 
Display  *display; 
Drawable  drawable; 
GC  gc; 
XArc  *arcs; 
int  narcs; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

dra viable  Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

arcs  Specifies  a  pointer  to  an  array  of  arc  definitions. 

narcs  Specifies  the  number  of  arcs  in  the  array. 

Description 

For  each  arc,  XFillArcs  fills  the  region  closed  by  the  specified  arc  and  one  or  two  line  seg 
ments,  depending  on  the  arc_mode  specified  in  the  GC.  It  does  not  draw  the  complete  out 
lines  of  the  arcs,  but  some  pixels  may  overlap. 

The  arc  forms  one  boundary  of  the  area  to  be  filled.  The  other  boundary  is  determined  by  the 
arc_mode  in  the  GC.  If  the  arc_mode  in  the  GC  is  ArcChord,  the  single  line  segment 
joining  the  endpoints  of  the  arc  is  used.  If  ArcPieSlice,  the  two  line  segments  joining  the 
endpoints  of  the  arc  with  the  center  point  are  used.  The  arcs  are  filled  in  the  order  listed  in  the 
array.  For  any  given  arc,  no  pixel  is  drawn  more  than  once.  If  filled  arcs  intersect,  pixels  will 
be  drawn  multiple  times. 

There  is  a  limit  to  the  number  of  arcs  that  can  be  filled  in  a  single  call,  that  varies  according  to 
the  server.  To  determine  how  many  arcs  you  can  fill  in  a  single  call,  you  find  out  your  server's 
maximum  request  size  using  XMaxRequestSize.  Subtract  3  and  divide  by  three,  and  this  is 
the  maximum  number  of  arcs  you  can  fill  in  a  single  XFillArcs  call. 

XFillArcs  use  these  graphics  context  components:  function,  plane_mask, 
f  ill_style,  arc_mode,  subwindow_mode,  clip_x_origin,  clip_y_origin,  and 
clipjmask.  This  function  also  uses  these  graphics  context  mode-dependent  components: 
foreground,  background,  tile,  stipple,  ts_x__origin,  and  ts_y_  origin. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Structures 

typedef  struct  { 
short  x,  y; 
unsigned  short  width,  height; 


Xlib  Reference  Manual  183 


XFillArcs 


(continued) 


Xlib  -  Drawing  Primitives 


short   anglel,    angle2;  /*      64ths   of   Degrees    */ 

}    XArc; 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related  Commands 

XClearArea,  XClearWindow, XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawArcs, XDrawFilled,  XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle,  XDrawRectangles, XDrawSegments, XFillArc,  XFill- 
Polygon,  XFillRectangle,  XFillRectangles. 
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— Xlib  -  Drawing  Primitives- 


f  XFillPolygon 


Name 

XFillPolygon  —  fill  a  polygon. 

Synopsis 

XFillPolygon  (display,  draw-able,  gc ,  points,  npoints,  shape,  mode) 
Display  *  display; 
Drawable  draw-able; 
GC  gc; 

XPoint  * points; 
int  npoints; 
int  shape; 
int  mode ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

dr a  wabl  e  Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

points  Specifies  a  pointer  to  an  array  of  points. 

npoin  t  s  Specifies  the  number  of  points  in  the  array. 

shape  Specifies  an  argument  that  helps  the  server  to  improve  performance.  Pass  the 

last  constant  in  this  list  that  is  valid  for  the  polygon  to  be  filled:  Complex, 
Nonconvex,  or  Convex. 

mode  Specifies  the  coordinate  mode.  Pass  either  CoordModeOrigin  or  Coord- 

ModePrevious. 

Description 

XFillPolygon  fills  the  region  closed  by  the  specified  path.  Some  but  not  all  of  the  path 
itself  will  be  drawn.  The  path  is  closed  automatically  if  the  last  point  in  the  list  does  not  coin 
cide  with  the  first  point.  No  pixel  of  the  region  is  drawn  more  than  once. 

The  mode  argument  affects  the  interpretation  of  the  points  that  define  the  polygon: 

CoordModeOrigin  indicates  that  all  points  are  relative  to  the  drawable's  origin. 

•         CoordModePrevious  indicates  that  all  points  after  the  first  are  relative  to  the  previ 
ous  point.  (The  first  point  is  always  relative  to  the  drawable's  origin.) 

The  shape  argument  allows  the  fill  routine  to  optimize  its  performance  given  tips  on  the  confi 
guration  of  the  area. 

Complex  indicates  the  path  may  self-intersect.  The  f  ill_rule  of  the  GC  must  be 
consulted  to  determine  which  areas  are  filled.  See  Volume  One,  Chapter  5,  The  Graphics 
Context,  for  a  discussion  of  the  fill  rules  EvenOddRule  and  WindingRule. 
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None  on  vex  indicates  the  path  does  not  self-intersect,  but  the  shape  is  not  wholly  con 
vex.  If  known  by  the  client,  specifying  Nonconvex  instead  of  Complex  may  improve 
performance.  If  you  specify  Nonconvex  for  a  self-intersecting  path,  the  graphics 
results  are  undefined. 

•  Convex  means  that  for  every  pair  of  points  inside  the  polygon,  the  line  segment  con 
necting  them  does  not  intersect  the  path.  This  can  improve  performance  even  more,  but 
if  the  path  is  not  convex,  the  graphics  results  are  undefined. 

Contiguous  coincident  points  in  the  path  are  not  treated  as  self-intersection. 

XFillPolygon  uses  these  graphics  context  components  when  filling  the  polygon  area: 

function,  plane_mask,  fill_style,  fill_rule,  subwindow_mode,  clip_ 
x_origin,  clip_y_origin,  and  clip_mask.  This  function  also  uses  these  mode-depen 
dent  components  of  the  GC:  foreground,  background,  tile,  stipple, 
ts_x_origin,  and  ts_y_origin. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Structures 

typedef  struct  { 

short  x,  y; 
}  XPoint; 

Errors 

BadDrawable 
BadGC 
BadMatch 
BadValue 

Related  Commands 

XClearArea, XClearWindow, XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawArcs, XDrawFilled,  XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArc,  XFillArcs, 
XFillRectangle,  XFillRectangles. 
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XFillRectangle 


Name 

XFillRectangle  —  fill  a  rectangular  area. 

Synopsis 

XFillRectangle (display,  drawable,  gc,  x,  y,  width,  height) 
Display  *display; 
Drawable  drawable; 
GC  gc; 
int  x ,  y  ; 
unsigned  int  width,  height; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

drawable      Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

x  Specify  the  x  and  y  coordinates  of  the  upper-left  corner  of  the  rectangle,  rela- 

y  live  to  the  origin  of  the  drawable. 

wi  dth  Specify  the  dimensions  in  pixels  of  the  rectangle  to  be  filled. 

height 

20  pixels  20  pixels 


Description 

XFillRectangle  fills  the  rectangular  area  in  the  specified  drawable  using  the  x  and  y  coor 
dinates,  width  and  height  dimensions,  and  graphics  context  you  specify.  XFill 
Rectangle  draws  some  but  not  all  of  the  path  drawn  by  XDrawRectangle  with  the  same 
arguments. 

XFillRectangle  uses  these  graphics  context  components:    function,  plane_mask, 

fill_style,    subwindow_mode,   clip_x_origin,   clip_y_origin,  and   clip_ 

mask.    This  function   also  uses  these  graphics   context  components   depending   on  the 

fill_style:  foreground,  background  tile,  stipple,  ts_x_origin,  and 

ts_y_origin. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 

The  Graphics  Context. 
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Errors 

BadDrawable 

BadGC 

BadMatch 


Related  Commands 

XClearArea, XClearWindow,  XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawArcs, XDrawFilled,  XDrawLine, XDrawLines, XDrawPoint,  XDrawPoints. 
XDrawRectangle,  XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, 
XFillPolygon,  XFillRectangles. 
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XFMIRectangles 


Name 

XFillRectangles  —  fill  multiple  rectangular  areas. 

Synopsis 

XFillRectangles  (display,  drawable,  gc ,  rectangles,  nrectangles) 
Display  * display ; 
Drawable  drawable; 
GC  gc  ; 

XRectangle  * rectangles; 
int  nrectangles; 


Arguments 

di spl ay 
drawable 


Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

Specifies  the  drawable. 
gc  Specifies  the  graphics  context. 

rectangles     Specifies  a  pointer  to  an  array  of  rectangles. 
nrectangles  Specifies  the  number  of  rectangles  in  the  array. 


20  pixels 


20  pixels 


Description 

XFillRectangles  fills  multiple  rectangular  areas  in  the  specified  drawable  using  the  graph 
ics  context. 

The  x  and  y  coordinates  of  each  rectangle  are  relative  to  the  drawable's  origin,  and  define  the 
upper  left  corner  of  the  rectangle.  The  rectangles  are  drawn  in  the  order  listed.  For  any  given 
rectangle,  no  pixel  is  drawn  more  than  once.  If  rectangles  intersect,  the  intersecting  pixels  will 
be  drawn  multiple  times. 

There  is  a  limit  to  the  number  of  rectangles  that  can  be  filled  in  a  single  call,  that  varies  accord 
ing  to  the  server.  To  determine  how  many  rectangles  you  can  fill  in  a  single  call,  you  find  out 
your  server's  maximum  request  size  using  XMaxRequestSize.  Subtract  3  and  divide  by 
two,  and  this  is  the  maximum  number  of  rectangles  you  can  fill  in  a  single  XD raw- 
Rectangles  call. 

XFillRectangles  uses  these  graphics  context  components:  function,  plane_mask, 
fill  style,  subwindow_mode,  clip_x_origin,  clip_y_origin,  and  clip_ 
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mask.  This  function  also  uses  these  graphics  context  components  depending  on  the  f  ill_ 
style:  foreground,  background,  tile,  stipple,  ts_x_origin,  and  ts_y_ 
origin. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text,  and  Chapter  5, 
The  Graphics  Context. 

Structures 

typedef   struct    { 

short   x,    y; 

unsigned  short  width,  height; 
}  XRectangle; 

Errors 

BadDrawable 

BadGC 

BadMatch 

Related  Commands 

XClearArea,  XClearWindow, XCopyArea, XCopyPlane, XDraw,  XDrawArc, 
XDrawArcs, XDrawFilled,  XDrawLine, XDrawLines, XDrawPoint, XDrawPoints, 
XDrawRectangle, XDrawRectangles, XDrawSegments, XFillArc, XFillArcs, 
XFillPolygon, XFillRectangle,  XFillRectangles. 
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XFindContext 

— Xlib  -  Context  Manager 

Name 

XFindContext  —  get  data  from  the  context  manager  (not  graphics  context). 

Synopsis 

int  XFindContext ( display,  w,  context,  data) 
Display  * display; 
Window  w; 
XContext  context; 
caddr_t  *data;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  with  which  the  data  is  associated. 

context  Specifies  the  context  type  to  which  the  data  corresponds. 

data  Returns  the  data. 

Description 

XFindContext  gets  data  that  has  been  assigned  to  the  specified  window  and  context  ID.  The 
context  manager  is  used  to  associate  data  with  windows  for  use  within  an  application. 

This  application  should  have  called  XUniqueContext  to  get  a  unique  ID,  and  then  xsave- 
Context  to  save  the  data  into  the  array.  The  meaning  of  the  data  is  indicated  by  the  context 
ID,  but  is  completely  up  to  the  client. 

XFindContext  returns  XCNOENT  (a  nonzero  error  code)  if  the  context  could  not  be  found  and 
zero  (0)  otherwise. 

For  more  information  on  the  context  manager,  see  Volume  One,  Chapter  13,  Other  Program 
ming  Techniques. 

Structures 

typedef  int  XContext/ 

Related  Commands 

XDeleteContext, XSaveContext,  XUniqueContext. 
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XFIush  v xnb .  Output  Bu((er_ 

Name 

XFIush  —  flush  the  request  buffer  (display  all  queued  requests). 

Synopsis 

XFIush  (display) 

Display    *display; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenoi splay. 

Description 

XFIush  sends  to  the  server  ("flushes")  all  requests  that  have  been  buffered  but  not  yet  sent. 

Flushing  is  done  automatically  when  input  is  read  if  no  matching  events  are  in  Xlib's  queue 
(with  XPending,  XNext Event,  or  XWindowEvent,  etc.),  or  when  a  call  is  made  that  gets 
information  from  the  server  (such  as  XQueryPointer,  XGetFontlnf  o)  so  XFIush  is  sel 
dom  needed.  It  is  used  when  the  buffer  must  be  flushed  before  any  of  these  calls  are  reached. 

For  more  information,  see  Volume  One,  Chapter  2,  X  Concepts,  and  Chapter  3,  Basic  Window 
Program. 

Related  Commands 

XSync. 
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Name 

XForceScreenSaver  —  turn  the  screen  saver  on  or  off. 

Synopsis 

XForceScreenSaver ( display,  mode) 
Display  *  display; 
int  mode ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

mode  Specifies  whether  the  screen  saver  is  active  or  reset.  The  possible  modes  are: 

ScreenSaverActive  or  ScreenSaverReset. 

Description 

XForceScreenSaver  resets  or  activates  the  screen  saver. 

If  the  specified  mode  is  ScreenSaverActive  and  the  screen  saver  currently  is  disabled,  the 
screen  saver  is  activated,  even  if  the  screen  saver  had  been  disabled  by  calling  xset  Screen- 
Saver  with  a  timeout  of  zero  (0).  This  means  that  the  screen  may  go  blank  or  have  some  ran 
dom  change  take  place  to  save  the  phosphors. 

If  the  specified  mode  is  ScreenSaverReset  and  the  screen  saver  currently  is  enabled,  the 
screen  is  returned  to  normal,  the  screen  saver  is  deactivated  and  the  activation  timer  is  reset  to 
its  initial  state  (as  if  device  input  had  been  received).  Expose  events  may  be  generated  on  all 
visible  windows  if  the  server  cannot  save  the  entire  screen  contents. 

For  more  information  on  the  screen  saver,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 

Errors 

BadValue 

Related  Commands 

XActivateScreenSaver, XGetScreenSaver,  XResetScreenSaver, XSet- 
ScreenSaver. 
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Name 

XFree  —  free  specified  memory  allocated  by  an  Xlib  function. 

Synopsis 

XFree  (data) 

caddr_t    data; 

Arguments 

data  Specifies  a  pointer  to  the  data  that  is  to  be  freed. 

Description 

XFree  is  a  general  purpose  routine  for  freeing  memory  allocated  by  Xlib  calls. 

Related  Commands 

Def aultScreen, XCloseDisplay,  XNoOp, XOpenDisplay. 
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Name 

XFreeColormap  —  delete  a  colormap  and  install  the  default  colormap. 

Synopsis 

XFreeColormap  ( display,  cmap) 
Display  *display; 
Colo  r map  cmap ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

cmap  Specifies  the  colormap  to  delete. 

Description 

XFreeColormap  destroys  the  specified  colormap,  unless  it  is  the  default  colormap  for  a 
screen.  That  is,  it  not  only  uninstalls  cmap  from  the  hardware  colormap  if  it  is  installed,  but 
also  frees  the  associated  memory  including  the  colormap  ID. 

XFreeColormap  performs  the  following  processing: 

If  cmap  is  an  installed  map  for  a  screen,  it  uninstalls  the  colormap  and  installs  the  default 
if  not  already  installed. 

If  cmap  is  defined  as  the  colormap  attribute  for  a  window  (by  XCreateWindow  or 
XChangeWindowAttributes),  it  changes  the  colormap  attribute  for  the  window  to 
the  constant  None,  generates  a  ColormapNotif  y  event,  and  frees  the  colormap.  The 
colors  displayed  with  a  colormap  of  None  are  server-dependent,  since  the  default  color- 
map  is  normally  used. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 
Errors 

BadColormap 

Related  Commands 

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate- 
Colormap, XGetStandardColormap, XInstallColormap,  XListlnstalled- 
Colormaps, XSetStandardColormap,  XSetWindowColormap,  XUninstall- 
Colormap. 
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•Xlib- Color  Cells- 


Name 

XFreeColors  —  free  colormap  cells  or  planes. 

Synopsis 

XFreeColors ( display,  cmap ,  pixels,  npixels,  planes) 
Display  *display; 
Colormap  cmap; 
unsigned  long  pixels []; 
int  npixels; 
unsigned  long  planes; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

cmap  Specifies  the  colormap. 

pixels  Specifies  an  array  of  pixel  values. 

npixels  Specifies  the  number  of  pixels. 

pi anes  Specifies  the  planes  you  want  to  free. 

Description 

XFreeColors  frees  the  cells  whose  values  are  computed  by  ORing  together  subsets  of  the 
planes  argument  with  each  pixel  value  in  the  pixels  array. 

If  the  cells  are  read/write,  they  become  available  for  reuse,  unless  they  were  allocated  with 
XAllocColorPlanes,  in  which  case  all  the  related  pixels  may  need  to  be  freed  before  any 
become  available. 

If  the  cells  were  read-only,  they  become  available  only  if  this  is  the  last  client  to  have  allocated 
those  shared  cells. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 

Errors 

BadAccess        Attempt  to  free  a  colorcell  not  allocated  by  this  client  (either  unallocated  or 
allocated  by  another  client). 

BadColormap 

BadValue          A  pixel  value  is  not  a  valid  index  into  cmap. 

Note:  if  more  than  one  pixel  value  is  in  error,  the  one  reported  is  arbitrary. 

Related  Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor 
Planes,  XAllocNamedColor, XLookupColor, XParseColor,  XQueryColor, 
XQueryColors, XStoreColor, XStoreColors,  XStoreNamedColor. 
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J  XFreeCursor 


Name 

XFreeCursor  —  release  a  cursor. 

Synopsis 

XFreeCursor ( display,  cursor) 
Display  * display; 
Cursor  cursor; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

cursor  Specifies  the  ID  of  the  cursor  to  be  affected. 

Description 

XFreeCursor  deletes  the  association  between  the  cursor  ID  and  the  specified  cursor.  The 
cursor  storage  is  freed  when  all  other  clients  have  freed  it.  Windows  with  their  cursor  attribute 
set  to  this  cursor  will  have  this  attribute  set  to  None  (which  implies  CopyFromParent).  The 
specified  cursor  ID  should  not  be  referred  to  again. 

Errors 

BadCursor 

Related  Commands 

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XDef ine- 
Cursor,  XQueryBestCursor, XQueryBestSize,  XRecolorCursor, XUndef ine- 
Cursor. 
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Name 

XFreeExtensionList  —  free  memory  allocated  for  a  list  of  installed  extensions. 

Synopsis 

XFreeExtensionList ( list) 
char    **Iist; 

Arguments 

list  Specifies   a  pointer   to   the   list   of  extensions   returned   from   XList- 

Extensions. 

Description 

XFreeExtensionList  frees  the  memory  allocated  by  XListExt  ens  ions. 

For  more  information,  see  Volume  One,  Chapter  13,  Other  Programming  Techniques. 

Related  Commands 

XListExt ens ions, XQueryExtension. 
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Name 

XFreeFont  —  unload  a  font  and  free  storage  for  the  font  structure. 

Synopsis 

XFreeFont  (  display,  font_struct  ) 
Display  *  display; 
XFontStruct  *font_struct  ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

f  ont_struct  Specifies  the  storage  associated  with  the  font. 

Description 

XFreeFont  frees  the  memory  allocated  for  the  font_struct  font  information  structure 
(XFontStruct)  filled  by  XQueryFont  or  XLoadQueryFont.  XFreeFont  frees  all  stor 
age  associated  with  the  font_struct  argument.  Neither  the  data  nor  the  font  should  be  ref 
erenced  again. 

The  server  unloads  the  font  itself  if  no  other  client  has  loaded  it. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

typedef  struct  { 

XExtData  *ext_data;  /*  hook  for  extension  to  hang  data  */ 

Font  fid;  /*  Font  ID  for  this  font  */ 

unsigned  direction;  /*  hint  about  direction  the  font  is  painted  */ 

unsigned  min_char_or_byte2;   /*  first  character  */ 

unsigned  max_char_or_byte2;   /*  last  character  */ 

unsigned  min_bytel;  /*  first  row  that  exists  */ 

unsigned  max_bytel;  /*  last  row  that  exists  */ 

Bool  all_chars_exist;  /*  flag  if  all  characters  have  nonzero  size*/ 

unsigned  def  ault_char;  /*  char  to  print  for  undefined  character  */ 

int  n_properties;  /*  how  many  properties  there  are  */ 

XFontProp  *properties;  /*  pointer  to  array  of  additional  properties*/ 

XCharStruct  min_bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  max_bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  *per_char;  /*  first_char  to  last_char  information  */ 

int  ascent;  /*  logical  extent  above  baseline  for  spacing  */ 

int  descent;  /*  logical  descent  below  baseline  for  spacing  */ 

}  XFontStruct; 

Errors 

BadFont 

Related  Commands 

XCreateFontCursor,  XFreeFontlnf  o,  XFreeFontNames,  XFreeFontPath, 
XGetFontPath,  XGetFontProperty,  XListFonts,  XListFontsWithlnf  o, 
XLoadFont,  XLoadQueryFont,  XQueryFont,  XSetFont,  XSetFontPath, 
XUnloadFont. 
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Name 

XFreeFontlnfo  —  free  the  memory  allocated  by  XListFontsWithlnf  o. 

Synopsis 

XFreeFontlnfo (names,  info,  actual_count) 
char  ** names; 
XFontStruct  *info; 
int  actual_count ; 

Arguments 

names  Specifies  a  pointer  to  the  list  of  font  names  that  were  returned  by  XList- 

FontsWithlnfo. 

info  Specifies  a  pointer  to  the  list  of  font  information  that  was  returned  by 

XListFontsWithlnf o. 

actual_count 

Specifies  the  number  of  matched  font  names  returned  by  XLis  t  Fonts - 
Withlnfo. 

Description 

XFreeFontlnfo  frees  the  list  of  font  information  structures  allocated  by  XListFonts 
Withlnf  o.  It  does  not  unload  the  specified  fonts  themselves. 

Structures 

typedef  struct  { 

XExtData  *ext_data;  /*  hook  for  extension  to  hang  data  */ 

Font  fid;  /*  Font  ID  for  this  font  */ 

unsigned  direction;  /*  hint  about  direction  the  font  is  painted  */ 

unsigned  min_char_or_byte2;   /*  first  character  */ 

unsigned  max  char  or  byte2;   /*  last  character  */ 

unsigned  min_bytel;  /*  first  row  that  exists  */ 

unsigned  max  bytel;  /*  last  row  that  exists  */ 

Bool  all_chars_exist;  /*  flag  if  all  characters  have  nonzero  size*/ 

unsigned  default_char;  /*  char  to  print  for  undefined  character  */ 

int  n_properties;  /*  how  many  properties  there  are  */ 

XFontProp  *properties;  /*  pointer  to  array  of  additional  properties*/ 

XCharStruct  min_bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  max  bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  *per_char;  /*  first_char  to  last_char  information  */ 

int  ascent;  /*  logical  extent  above  baseline  for  spacing  */ 

int  descent;  /*  logical  descent  below  baseline  for  spacing  */ 

}  XFontStruct; 

Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontNames, XGetFontPath, XGetFont- 
Property, XListFonts, XListFontsWithlnf o, XLoadFont,  XLoadQueryFont, 
XQueryFont, XSetFont, XSetFontPath, XUnloadFont. 
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— Xlib -Fonts  • 


J  XFreeFontNames 


Name 

XFreeFontNames  —  free  the  memory  allocated  by  XListFonts. 
Synopsis 

XFreeFontNames (list) 
char    *list  [  ]  ; 

Arguments 

list  Specifies  the  array  of  font  name  strings  to  be  freed. 

Description 

XFreeFontNames  frees  the  array  of  strings  returned  by  XListFonts. 

Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o,  XFreeFontPath, XGetFont- 
Path,  XGetFontProperty, XListFonts,  XListFontsWithlnf o, XLoadFont, 
XLoadQueryFont, XQueryFont, XSetFont,  XSetFontPath,  XUnloadFont. 
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XFreeFontPath  \ x,,b-Fon,s- 

Name 

XFreeFontPath  —  free  the  memory  allocated  by  XGetFontPath. 

Synopsis 

XFreeFontPath (list) 
char    **list; 

Arguments 

list  Specifies  an  array  of  strings  allocated  by  XGetFontPath. 

Description 

XFreeFontPath  frees  the  data  used  by  the  array  of  pathnames  returned  by  XGetFont 
Path. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XGet 
FontPath,  XGetFontProperty, XListFonts,  XListFontsWithlnf o, XLoad- 
Font,  XLoadQueryFont, XQueryFont, XSetFont,  XSetFontPath, XUnloadFont. 
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-Xlib  -  Graphics  Context '  XFreeGC 

Name 

XFreeGC  —  free  a  graphics  context. 

Synopsis 

XFreeGC  (display,  gc) 
Display  *  display; 
GC  gc  ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

gc  Specifies  the  graphics  context  to  be  freed. 

Description 

XFreeGC  frees  all  memory  associated  with  a  graphics  context,  and  removes  the  GC  from  the 
server  and  display  hardware. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 

Errors 

BadGC 

Related  Commands 

Def aultGC, XChangeGC, XCopyGC,  XCreateGC,  XGContextFromGC, XSetArcMode, 
XSetBackground,  XSetClipMask,  XSetClipOrigin,  XSetClipRectangles, 
XSetDashes,  XSetFillRule, XSetFillStyle, XSetForeground,  XSet- 
Function, XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, 
XSetState, XSetStipple,  XSetSubwindowMode,  XSetTSOrigin. 
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XFreeModifiermap  \ 


X|lb  _ 


Name 

XFreeModifiermap  —  destroy  and  free  a  keyboard  modifier  mapping  structure. 

Synopsis 

XF  r  eeModi  f  ie  rmap  (  modmap  ) 

XModif  ierKeymap  *  modmap; 

Arguments 

modmap  Specifies  a  pointer  to  the  XModif  ierKeymap  structure  to  be  freed. 

Description 

XFreeModifiermap  frees  an  XModif  ierKeymap  structure  originally  allocated  by  XNew- 
Modif  ierMap  or  XGetModif  ierMapping. 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
Structures 

typedef  struct  { 

int  max_keypermod;     /*  server's  max  number  of  keys  per  modifier  */ 
KeyCode  *modif  iermap;  /*  an  8  by  max_keypermod  array  of 

*  keycodes  to  be  used  as  modifiers  */ 

}  XModif  ierKeymap; 

Related  Commands 

XChangeKeyboardMapping,  XDeleteModif  iermapEntry,  XGetKeyboard- 
Mapping,  XGetModif  ierMapping,  XInsertModif  iermapEntry,  XKeycode- 
ToKeysym,  XKeysymToKeycode,  XKeysymToString,  XLookupKeysym,  XLookup- 
String,  XNewModif  ierMap,  XQueryKeymap,  XRebindKeySym,  XRef  resh- 
KeyboardMapping,  XSetModif  ierMapping,  XStringToKeysym. 
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-Mb  -  Pixmaps  and  TNes / 

Name 

XFreePixmap  —  free  a  pixmap  ID. 

Synopsis 

XFreePixmap  ( display,  pixmap) 
Display  * display; 
Pixmap  pixmap; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

pixmap  Specifies  the  pixmap  whose  ID  should  be  freed. 

Description 

XFreePixmap  disassociates  a  pixmap  ID  from  its  resource.  If  no  other  client  has  an  ID  for 
that  resource,  it  is  freed.  The  Pixmap  should  never  be  referenced  again  by  this  client.  If  it  is, 
the  ID  will  be  unknown  and  a  BadPixmap  error  will  result. 

Errors 

BadPixmap 

Related  Commands 

XCreateBitmapFromData,  XCreatePixmap,  XCreatePixmapFromBitmapData, 
XQueryBestSize, XQueryBestStipple, XQueryBestTile,  XReadBitmapFile, 
XSetTile, XSetWindowBackgroundPixmap,  XSetWindowBorderPixmap, 
XWriteBitmapFile. 
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XFreeStringList  V Vl] 

^ Xlib  -  Window  Manager  Hints- 
Name 

XFreeStringList  —  free  the  in-memory  data  associated  with  the  specified  string  list. 

Synopsis 

void  XFreeStringList (list) 
char  **Iist; 

Arguments 

list  Specifies  the  list  of  strings  to  be  freed. 

Availability 

Release  4  and  later. 

Description 

XFreeStringList  releases  memory  allocated  by  XTextPropertyToStringList. 

Related  Commands 

XGetTextProperty,    XSetTextProperty,    XStringListToTextProperty, 
XTextPropertytoStringList. 
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-xub  -  Graphic,  con,8x« /  XGContextFromGC 

Name 

XGContextFromGC  —  obtain  the  GContext  (resource  ID)  associated  with  the  specified 
graphics  context. 

Synopsis 

GContext    XGContextFromGC ( gc) 
GC   gc; 

Arguments 

gc  Specifies  the  graphics  context  of  the  desired  resource  ID. 

Description 

XGContextFromGC  extracts  the  resource  ID  from  the  GC  structure.  The  GC  structure  is 
Xlib's  local  cache  of  GC  values  and  contains  a  field  for  the  GContext  ID.  This  function  is 
essentially  a  macro  that  accesses  this  field,  since  the  GC  structure  is  intended  to  be  opaque. 

A  GContext  is  needed  to  set  a  field  of  the  xvisuallnf  o  structure  prior  to  calling  XGet- 
Visuallnf o. 

Related  Commands 

Def aultGC, XChangeGC, XCopyGC,  XCreateGC,  XFreeGC,  XSetArcMode, XSet- 
Background, XSetClipMask, XSetClipOrigin,  XSetClipRectangles, XSet- 
Dashes, XSetFillRule, XSetFillStyle,  XSetForeground, XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes,  XSetPlaneMask,  XSetState, 
XSetStipple, XSetSubwindowMode,  XSetTSOrigin. 
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XGeometry  v ^ 

v Xlib  -  Standard  Geometry- 
Name 

XGeometry  —  calculate  window  geometry  given  user  geometry  string  and  default  geometry. 

Synopsis 

int    XGeometry ( display,    screen,    user_geom,    default_geomr    bwidth, 

fwidthr    f height ,    xadder ,    yadder f    x,    y,    width,    height) 
Display    *display; 
int    screen; 

char    *user_geomr    *default_geom; 
unsigned   int   bwidth; 
unsigned   int    f width r    f height ; 
int    xadder,    yadder; 
int    *xr    *y,    *  width,    *height;/*   RETURN    */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

screen  Specifies  which  screen  the  window  is  on. 

user_geom       Specifies  the  user  or  program  supplied  geometry  string,  perhaps  incomplete. 

de  fa  u  1 1_  ge  om 

Specifies  the  default  geometry  string  and  must  be  complete. 

bwi  dth  Specifies  the  border  width. 

f  height  Specify  the  font  height  and  width  in  pixels  (increment  size). 

f width 

xadder  Specify  additional  interior  padding  in  pixels  needed  in  the  window, 

yadder 

x  Return  the  user-specified  or  default  coordinates  of  the  window. 

y 

wi  dth  Return  the  window  dimensions  in  pixels. 

height 

Description 

XGeometry  has  been  superseded  by  XWMGeometry  as  of  Release  4. 

XGeometry  returns  the  position  and  size  of  a  window  given  a  user-supplied  geometry 
(allowed  to  be  partial)  and  a  default  geometry.  Each  user-supplied  specification  is  copied  into 
the  appropriate  returned  argument,  unless  it  is  not  present,  in  which  case  the  default  specifica 
tion  is  used.  The  default  geometry  should  be  complete  while  the  user-supplied  one  may  not  be. 

XGeometry  is  useful  for  processing  command  line  options  and  user  preferences.  These  geom 
etry  strings  are  of  the  form: 

=<width>x<height> { +- } <xoffset> ( +- } <yoffset> 
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Xlib  -  Standard  Geometry  (continued)  XGeometry 

The  "="  at  the  beginning  of  the  string  is  now  optional.  (Items  enclosed  in  <>  are  integers,  and 
items  enclosed  in  {}  are  a  set  from  which  one  item  is  to  be  chosen.  Note  that  the  brackets 
should  not  appear  in  the  actual  string.) 

The  XGeometry  return  value  is  a  bitmask  that  indicates  which  values  were  present  in 
user_geom.  This  bitmask  is  composed  of  the  exclusive  OR  of  the  symbols  XValue, 
YValue,  WidthValue,  HeightValue,  XNegative,  or  YNegative. 

If  the  function  returns  either  xvalue  or  YValue,  you  should  place  the  window  at  the 
requested  position.  The  border  width  (bwidtti),  size  of  the  width  and  height  increments  (typi 
cally  fwidth  and  f height),  and  any  additional  interior  space  (xadder  and  yadder)  are 
passed  in  to  make  it  easy  to  compute  the  resulting  size. 

Related  Commands 

XParseGeometry, XTranslateCoordinates,  XWMGeometry. 
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XGetAtomName  V ™ 

^ Xlib  -  Properties- 
Name 

XGetAtomName  —  get  a  string  name  for  a  property  given  its  atom. 

Synopsis 

char  *XGetAtomName  (  display,  atom) 
Display  *display; 
Atom  atom; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

atom  Specifies  the  atom  whose  string  name  you  want  returned. 

Description 

An  atom  is  a  number  identifying  a  property.  Properties  also  have  a  string  name.  XGetAtom 
Name  returns  the  string  name  that  was  specified  in  the  original  call  to  xinternAtom  that 
returned  this  atom,  or,  for  predefined  atoms,  a  string  version  of  the  symbolic  constant  without 
the  XA_  is  returned.  If  the  specified  atom  is  not  defined,  XGetAtomName  returns  NULL,  and 
generates  a  BadAtom  error. 

For  example,  XGetAtomName  returns  "XA_WM_CLASS"  (a  string)  when  passed  the  prede 
fined  atom  XA_WM_CLASS  (a  defined  constant). 

You  should  free  the  resulting  string  with  XFree  when  it  is  no  longer  needed. 
XinternAtom  performs  the  inverse  function,  returning  the  atom  given  the  string. 

Errors 

BadAtom 

Related  Commands 

XChangeProperty, XDeleteProperty, XGetFontProperty,  XGetWindow- 
Property, XinternAtom,  XListProperties,  XRotateWindowProperties, 
XSetStandardProperties. 
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-X.ib-W.ndowManagerH.n,, /  XGetClaSSHint 

Name 

XGetClassHint  —  get  the  XA_WM_CLASS  property  of  a  window. 

Synopsis 

Status  XGetClassHint (display,  v,  class_hints) 
Display  *display; 
Window  w; 
XClassHint  *class_hints ;   /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  for  which  the  property  is  desired. 

class_hints  Returns  the  XClassHints  structure. 

Description 

XGetClassHint  obtains  the  XA_WM_CLASS  property  for  the  specified  window.  This  property 
stores  the  resource  class  and  instance  name,  that  the  window  manager  uses  to  get  any  resource 
settings  that  may  control  how  the  window  manager  manages  the  application  that  set  this  prop 
erty.  XGetClassHint  returns  a  Status  of  zero  on  failure,  nonzero  on  success. 

The  XClassHint  structure  returned  contains  res_class,  which  is  the  name  of  the  client 
such  as  "emacs",  and  res_name,  which  should  be  the  first  of  the  following  that  applies: 

command  line  option  (-rn  name) 

a  specific  environment  variable  (e.g.,  RESOURCE_NAME) 

the  trailing  component  of  argv  [  0  ]  (after  the  last  /) 

To  free  res_name  and  res_class  when  finished  with  the  strings,  use  XFree. 
For  more  information  on  using  hints,  see  Volume  One,  Chapter  W,Interclient  Communication. 

Structures 

typedef   struct    { 

char    *res_name; 

char    *res_class; 
}    XClassHint; 

Errors 

BadWindow 

Related  Commands 

XAllocClassHint, XFetchName, XGetlconName,  XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetCommand, XSetlconName,  XSetlconSizes, XSet- 
NormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, XSet- 
ZoomHints,  XStoreName,  XSetWMProperties, XSetWMProperties. 
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XGetCommand  I 

v Xllb  -  Window  Manager  Hints- 
Name 

XGetCommand  —  get  the  XA_WM_COMMAND  property  (command  line  arguments). 

Synopsis 

Status   XGetCommand  (display,    w,    argv_return,    argc_return) 
Display    ^display; 
Window   w; 

char    ***argv_return; 
int    *argc_return; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window. 

argv_return  Returns  the  application's  argument  list. 
argc_return  Returns  the  number  of  arguments  returned. 

Description 

XGetCommand  reads  the  XA_WM_COMMAND  property  from  the  specified  window  and  returns  a 
string  list.  If  the  XA_WM_COMMAND  property  exists,  it  is  of  type  XA_STRING  and  format  8.  If  suf 
ficient  memory  can  be  allocated  to  contain  the  string  list,  XGetCommand  fills  in  the 
argv_return  and  argc_return  arguments  and  returns  a  non-zero  status.  Otherwise,  it 
returns  a  zero  status.  To  free  the  memory  allocated  to  the  string  list,  use  XFreeStringList. 

Errors 

BadWindow 

Related  Commands 

XFetchName, XGetClassHint, XGetlconName,  XGetlconSizes,  XGetNormal- 
Hints,  XGetSizeHints, XGetTransientForHint, XGetWMHints,  XGetZoom- 
Hints,  XSetClassHint, XSetlconName, XSetlconSizes, XSetNormalHints, 
XSetSizeHints,  XSetTransientForHint, XSetWMHints, XSetZoomHints, 
XStoreName. 
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XGetDefault 


Name 

XGetDefault  —  extract  an  option  value  from  the  resource  database. 

Synopsis 

char  *XGetDefault  (display,  program,  option) 
Display  *  display  ; 
char  *  program; 
char  *  opt  ion; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

program        Specifies  the  program  name  to  be  looked  for  in  the  resource  database.  The  pro 
gram  name  is  usually  argv  [  0  ]  ,  the  first  argument  on  the  UNIX  command  line. 

option  Specifies  the  option  name  or  keyword.  Lines  containing  both  the  program 

name  and  the  option  name,  separated  only  by  a  period  or  asterisk,  will  be 
matched. 

Description 

XGetDefault  returns  a  character  string  containing  the  user's  default  value  for  the  specified 
program  name  and  option  name.  XGetDefault  returns  NULL  if  no  key  can  be  found  that 
matches  option  and  program.  For  a  description  of  the  matching  rules,  see  XrmGet- 
Resource. 

The  strings  returned  by  XGetDefault  are  owned  by  Xlib  and  should  not  be  modified  or  freed 
by  the  client. 

Lines  in  the  user's  resource  database  look  like  this: 

xterm.  foreground:  #cOcOff 

xterm.  geometry  :  =81x28 

xterm.  saveLines  :  256 

xterm.  font:  8x13 

xterm.  keyMapFile:  /usr/black/  .keymap 

xterm.  activelcon:  on 

xmh.  header.  font  9x15 

The  portion  on  the  left  is  known  as  a  key;  the  portion  on  the  right  is  the  value.  Upper  or  lower 
case  is  important  in  keys.  The  convention  is  to  capitalize  only  the  second  and  successive  words 
in  each  option,  if  any. 

Resource  specifications  are  usually  loaded  into  the  XA_RESOURCE_MANAGER  property  on  the 
root  window  at  login.  If  no  such  property  exists,  a  resource  file  in  the  user's  home  directory  is 
loaded.  On  a  UNIX-based  system,  this  file  is  $HOMEIXdefoults.  After  loading  these  defaults, 
XGetDefault  merges  additional  defaults  specified  by  the  XENVIRONMENT  environment 
variable.  If  XENVIRONMENT  is  defined,  it  contains  a  full  path  name  for  the  additional  resource 
file.  If  XENVIRONMENT  is  not  defined,  XGetDefault  looks  for  $HOMEI  Xdefoults-name, 
where  name  specifies  the  name  of  the  machine  on  which  the  application  is  running. 
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XGetDefault  (continued)  Xlib  -  User  Preferences 

The  first  invocation  of  XGetDefault  reads  and  merges  the  various  resource  files  into  Xlib  so 
that  subsequent  requests  are  fast  Therefore,  changes  to  the  resource  files  from  the  program 
will  not  be  felt  until  the  next  invocation  of  the  application. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 
Related  Commands 

XAutoRepeatOf  f ,  XAutoRepeatOn,  XBell,  XChangeKeyboardControl,  XGet- 
KeyboardControl.XGetPointerControl. 
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-xnb  -  Error  Handling /  XGetErrorDatabaseText 

Name 

XGetErrorDatabaseText  —  obtain  error  messages  from  the  error  database. 

Synopsis 

XGetErrorDatabaseText ( display,    name,    message, 

default_string,    buffer,    length) 
Display   display; 
char   *name,    *message; 
char    *default_string; 

char    * buffer;  /*  RETURN    */ 

int    length; 

Arguments 

di  spl  ay         Specifies  a  connection  to  an  X  server;  returned  from  XOpe nD  i  s p  1  a y . 

name  Specifies  the  name  of  the  application. 

message         Specifies  the  type  of  the  error  message.  One  of  XProtoError,  xiib- 
Message,  or  XRequestMa  jor  (see  Description  below). 

default_string 

Specifies  the  default  error  message. 

buffer          Returns  the  error  description. 
length  Specifies  the  size  of  the  return  buffer. 

Description 

XGetErrorDatabaseText  returns  a  message  from  the  error  message  database.  Given 
name  and  message  as  keys,  XGetErrorDatabaseText  uses  the  resource  manager  to 
look  up  a  string  and  returns  it  in  the  buffer  argument.  Xlib  uses  this  function  internally  to  look 
up  its  error  messages.  On  a  UNIX-based  system,  the  error  message  database  is  usually 
lusrlliblXl  1  IXErrorDB . 

The  name  argument  should  generally  be  the  name  of  your  application.  The  message  argu 
ment  should  indicate  which  type  of  error  message  you  want.  Three  predefined  message  types 
are  used  by  Xlib  to  report  errors: 

XProtoError        The  protocol  error  number  is  used  as  a  string  for  the  message  argument. 
xlibMessage        These  are  the  message  strings  that  are  used  internally  by  Xlib. 
XReque s  tMa  jor    The  major  request  protocol  number  is  used  for  the  message  argument. 

If  no  string  is  found  in  the  error  database,  XGetErrorDatabaseText  returns  the 
def  ault_string  that  you  specify  to  the  buffer.  The  string  in  buffer  will  be  of  length 
length.  For  more  information,  see  Volume  One,  Chapter  3,  Basic  Window  Program. 

Related  Commands 

XDisplayName, XGetErrorText,  XSetAf terFunction,  XSetErrorHandler, 
XSetlOErrorHandler, XSynchronize. 
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XGetErrorText  \ Xllb  _  Error  Handnng_ 

Name 

XGetErrorText  —  obtain  a  description  of  error  code. 

Synopsis 

XGetErrorText ( display,  code,  buffer,  length) 
Display  *display; 
int  code ; 

char  * buffer;  /*  RETURN  */ 

int  length; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

code  Specifies  the  error  code  for  which  you  want  to  obtain  a  description. 

buffer  Returns  a  pointer  to  the  error  description  text. 

length  Specifies  the  size  of  the  buffer. 

Description 

XGetErrorText  obtains  textual  descriptions  of  errors.  XGetErrorText  returns  a  pointer 
to  a  null-terminated  string  describing  the  specified  error  code  with  length  length.  This  string 
is  copied  from  static  data  and  therefore  may  be  freed.  This  routine  allows  extensions  to  the 
Xlib  library  to  define  their  own  error  codes  and  error  strings  that  can  be  accessed  easily. 

For  more  information,  see  Volume  One,  Chapter  3,  Basic  Window  Program. 
Related  Commands 

XDisplayName, XGetErrorDatabaseText, XSetAf terFunction, XSetError- 
Handler, XSetlOErrorHandler, XSynchronize. 
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—  XI  ib- Fonts- 


J  XGetFontPath 


Name 

XGetFontPath  —  get  the  current  font  search  path. 

Synopsis 

char  **XGetFontPath ( display,  npaths) 
Display  ^display; 
int  * npaths;  /*  RETURN  number  of  elements  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

npaths  Returns  the  number  of  strings  in  the  font  path  array. 

Description 

XGetFontPath  allocates  and  returns  an  array  of  strings  containing  the  search  path  for  fonts. 
The  data  in  the  font  path  should  be  freed  when  no  longer  needed. 

Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontProperty, XListFonts,  XListFontsWithlnf o, XLoad- 
Font,  XLoadQueryFont, XQueryFont, XSetFont,  XSetFontPath,  XUnloadFont. 
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XGetFontProperty 


X 


•Xlib- Properties- 


Name 

XGetFontProperty  —  get  a  font  property  given  its  atom. 

Synopsis 

Bool  XGetFontProperty (font_structf  atom,  value) 
XFontStruct  *f ont_struct ; 
Atom  atom; 
unsigned  long  *value;      /*  RETURN  */ 

Arguments 

font   struct  Specifies  the  storage  associated  with  the  font. 


atom 
value 


Specifies  the  atom  associated  with  the  property  name  you  want  returned. 


Returns  the  value  of  the  font  property. 

Description 

XGetFontProperty  returns  the  value  of  the  specified  font  property,  given  the  atom  for  that 
property.  The  function  returns  False  if  the  atom  was  not  defined,  or  True  if  was  defined. 

There  are  a  set  of  predefined  atoms  for  font  properties  which  can  be  found  in  <XlllXatom.h>. 
These  atoms  are  listed  and  described  in  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
This  set  contains  the  standard  properties  associated  with  a  font.  The  predefined  font  properties 
are  likely  but  not  guaranteed  to  be  present  for  any  given  font. 

See  Volume  One,  Appendix  I,  Logical  Font  Description  Conventions,  for  more  information  on 
font  properties. 


Structures 

typedef  struct  { 

XExtData  *ext_data; 
Font  fid; 

unsigned  direction; 
unsigned  min_char_or_byte2; 
unsigned  max_char_or_byte2; 
unsigned  min_bytel; 
unsigned  max_bytel; 
Bool  all_chars_exist; 
unsigned  def ault_char; 
int  n_properties; 
XFontProp  ^properties; 
XCharStruct  min_bounds; 
XCharStruct  max  bounds; 


XCharStruct  ' 
int  ascent; 
int  descent; 
}  XFontStruct; 


per_char; 


/*  hook  for  extension  to  hang  data  */ 

/*  Font  ID  for  this  font  */ 

/*  hint  about  direction  the  font  is  painted  */ 

/*  first  character  */ 

/*  last  character  */ 

/*  first  row  that  exists  */ 

/*  last  row  that  exists  */ 

/*  flag  if  all  characters  have  nonzero  size*/ 

/*  char  to  print  for  undefined  character  */ 

/*  how  many  properties  there  are  */ 

/*  pointer  to  array  of  additional  properties*/ 

/*  minimum  bounds  over  all  existing  char*/ 

/*  minimum  bounds  over  all  existing  char*/ 

/*  first_char  to  last__char  information  */ 

/*  logical  extent  above  baseline  for  spacing  */ 

/*  logical  descent  below  baseline  for  spacing  */ 


Related  Commands 

XChangeProperty, XDeleteProperty,  XGetAtomName,  XGetWindowProperty, 
XInternAtom,  XListProperties, XRotateWindowProperties, XSetStandard- 
Properties. 
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— Xlib  -  Window  Manager  Hints- 


XGetGCValues 


Name 

XGetGCValues  —  obtain  components  of  a  given  GC  from  Xlib's  GC  cache. 

Synopsis 

Status  XGetGCValues (display,  gc,  valuemask,  values) 
Display  ^display; 
GC  gc; 

unsigned  long  valuemask; 
XGCValues  *  values; 


Arguments 

di  sp  1  ay 

gc 

valuemask 


values 


/*  RETURN  */ 

Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 
Specifies  the  GC. 

Specifies  which  components  in  the  GC  are  to  be  returned  in  the  values 
argument.  This  argument  is  the  bitwise  inclusive  OR  of  one  or  more  of  the 
valid  GC  component  mask  bits. 

Returns  the  GC  values  in  the  specified  XGCValues  structure. 


Availability 

Release  4  and  later. 

Description 

XGetGCValues  returns  the  components  specified  by  valuemask  for  the  specified  GC.  Note 
that  the  clip  mask  and  dash  list  (represented  by  the  GCClipMask  and  GCDashList  bits, 
respectively,  in  the  valuemask)  cannot  be  requested.  If  the  valuemask  contains  a  valid  set  of 
GC  mask  bits  (any  of  those  listed  in  the  Structures  section  with  the  exception  of  GCClipMask 
and  GCDashList)  and  no  error  occur,  XGetGCValues  sets  the  requested  components  in 
values  and  returns  a  nonzero  status.  Otherwise,  it  returns  a  zero  status. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 


Structures 

typedef  struct  { 

int  function;  /* 

unsigned  long  plane_mask;  /* 

unsigned  long  foreground;  /* 

unsigned  long  background;  /* 

int  line_width;  /* 

int  line_style;  /* 

int  cap_style;  /* 

int  join_style;  /* 

int  fill_style;  /* 

int  fill_rule;  /* 

int  arc_mode;  /* 

Pixmap  tile;  /* 

Pixmap  stipple;  /* 

int  ts_x_origin;  /* 


logical  operation  */ 

plane  mask  */ 

foreground  pixel  */ 

background  pixel  */ 

line  width  */ 

LineSolid,  LineOnOf fDash,  LineDoubleDash  */ 

CapNotLast,  CapButt,  CapRound,  CapPro jecting  */ 

JoinMiter,  JoinRound,  JoinBevel  */ 

FillSolid,  Fill-Tiled,  FillStippled  */ 

EvenOddRule,  WindingRule  */ 

ArcPieSlice,  ArcChord  */ 

tile  pixmap  for  tiling  operations  */ 

stipple  1  plane  pixmap  for  stipping  */ 

offset  for  tile  or  stipple  operations  */ 
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XGetGCValues 


(continued) 


Xlib  -  Window  Manager  Hints 


int  ts_y_origin; 
Font  font; 
int  subwindow  mode; 
Bool  graphics_exposures; 
int  clip_x_origin; 
int  clip_y_origin; 
Pixmap  clip_mask; 
int  dash_offset; 
char  dashes; 
}  XGCValues; 


/*  default  text  font  for  text  operations  */ 

/*  ClipByChildren,  Includelnferiors  */ 

/*  generate  events  on  XCopyArea,  XCopyPlane  */ 

/*  origin  for  clipping  */ 

/*  bitmap  clipping;  other  calls  for  rects  */ 

/*  patterned/dashed  line  information  */ 


#define 

GCFunction               (1L«0) 

#define 

GCPlaneMask              (1L«1) 

#define 

GCForeground             (1L«2) 

#define 

GCBackground             (1L«3) 

#define 

GCLineWidth              (1L«4) 

#define 

GCLineStyle               (1L«5) 

#define 

GCCapStyle               (1L«6) 

#define 

GCJoinStyle              (1L«7) 

#define 

GCFillStyle               (1L«8) 

#define 

GCFillRule                (1L«9) 

fdefine 

GCTile                    (1L«10) 

#define 

GCStipple                 (1L«11) 

#define 

GCTileStipXOrigin        (1L«12) 

#def  ine 

GCTileStipYOrigin        (1L«13) 

tdefine 

GCFont                    (1L«14) 

#def  ine 

GCSubwindowMode          (1L«15) 

#define 

GCGraphicsExposures      (1L«16) 

#define 

GCClipXOrigin            (1L«17) 

#define 

GCClipYOrigin            (1L«18) 

#def  ine 

GCClipMask               (1L«19) 

tdefine 

GCDashOffset             (1L«20) 

#def  ine 

GCDashList               (1L«21) 

#define 

GCArcMode                (1L«22) 

/*  not  valid  in  this  call  */ 
/*  not  valid  in  this  call  */ 


Related  Commands 

XChangeGC, XCopyGC,  XCreateGC. 
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—  Xlib  -  Window  Attributes- 


J  XGetGeometry 


Name 

XGetGeometry  —  obtain  the  current  geometry  of  drawable. 

Synopsis 

Status    XGetGeometry (display,    drawable,     root,  x,    y, 

width,    height,    border_ width,    depth) 
Display    ^display; 
Drawable    drawable; 

Window   *root;  /*  RETURN  */ 

int    *x,     *y;  /*    RETURN  */ 

unsigned   int    *width,    *height;         /*  RETURN  */ 

unsigned   int    *border_width ;  /*  RETURN  */ 

unsigned   int    *  depth;  /*  RETURN  */ 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawabl  e       Specifies  the  drawable,  either  a  window  or  a  pixmap. 
root  Returns  the  root  window  ID  of  the  specified  window. 

x  Return  the  coordinates  of  the  upper- left  pixel  of  the  window's  border,  relative 

y  to  its  parent's  origin.  For  pixmaps,  these  coordinates  are  always  zero. 

width  Return  the  dimensions  of  the  drawable.  For  a  window,  these  return  the  inside 

height  size  (not  including  the  border). 

border_width 

Returns  the  borderwidth,  in  pixels,  of  the  window's  border,  if  the  drawable  is  a 
window.  Returns  zero  if  the  drawable  is  a  pixmap. 

depth  Returns  the  depth  of  the  pixmap  or  window  (bits  per  pixel  for  the  object). 

Description 

This  function  gets  the  current  geometry  of  a  drawable,  plus  the  ID  of  the  root  window  of  the 
screen  the  window  is  on. 

XGetGeometry  returns  a  Status  of  zero  on  failure,  or  nonzero  on  success. 

Errors 

BadDrawable 

Related  Commands 

XConf igureWindow, XGetWindowAttributes,  XMoveResizeWindow, XMove- 
Window,  XResizeWindow. 
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XGetlconName  V Xlib  _  Wlndow  Manager  Hln,s_ 

Name 

XGetlconName  —  get  the  name  to  be  displayed  in  an  icon. 

Synopsis 

Status    XGetlconName  ( display,    w,    icon_name) 
Display    *display; 
Window   w; 
char    **icon_name;  /*  RETURN    */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  whose  icon  name  you  want  to  leam. 

icon_name  Returns  a  pointer  to  the  name  to  be  displayed  in  the  window's  icon.  The 
name  should  be  a  null-terminated  string.  If  a  name  hasn't  been  assigned  to 
the  window,  XGetlconName  sets  this  argument  to  NULL.  When  finished 
with  it,  a  client  must  free  the  icon  name  string  using  XFree. 

Description 

XGetlconName  is  superseded  by  XGetWMlconName  in  Release  4.  XGetlconName  reads 
the  icon  name  property  of  a  window.  This  function  is  primarily  used  by  window  managers  to 
get  the  name  to  be  written  in  a  window's  icon  when  they  need  to  display  that  icon. 

XGetlconName  returns  a  nonzero  Status  if  it  succeeds,  and  zero  if  no  icon  name  has  been 
set  for  the  argument  window. 

For  more  information,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Errors 

BadWindow 

Related  Commands 

XFetchName, XGetClassHint, XGetlconSizes, XGetNormalHints, XGetSize- 
Hints,  XGetTransientForHint, XGetWMHints, XGetZoomHints,  XSetClass- 
Hint, XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints, XSet- 
SizeHints,  XSetTransientForHint, XSetWMHints,  XSetZoomHints,  XStore- 
Name. 
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-XHb-W.ndowM.n.g.rH.n., /  XGetlCOnSizeS 

Name 

XGetlconSizes  —  get  preferred  icon  sizes. 

Synopsis 

Status  XGetlconSizes (display,  w,  size_list,  count) 
Display  *display; 
Window  w; 

XlconSize  **size_list;     /*  RETURN  */ 
int  *  count;  /*  RETURN  */ 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID  (usually  of  the  root  window). 

si  ze_l  1st    Returns  a  pointer  to  the  size  list. 

count  Returns  the  number  of  items  in  the  size  list. 

Description 

XGetlconSizes  reads  the  XA_WM_ICON_SIZE  property  that  should  be  set  by  the  window 
manager  to  specify  its  desired  icon  sizes.  XGetlconSizes  returns  a  Status  of  zero  if  a 
window  manager  has  not  set  icon  sizes,  and  a  nonzero  Status  otherwise.  This  function 
should  be  called  by  all  programs  to  find  out  what  icon  sizes  are  preferred  by  the  window  man 
ager.  The  application  should  then  use  XSetWMHints  to  supply  the  window  manager  with  an 
icon  pixmap  or  window  in  one  of  the  supported  sizes.  To  free  the  data  allocated  in 
size_list,  use  XFree. 

For  more  information,  see  Volume  One,  Chapter  10,  Interclient  Communication. 
Structures 

typedef  struct  { 

int  min_width,  min_height; 
int  max_width,  max_height; 
int  width_inc,  height_inc; 
}  XlconSize; 

/*  width_inc  and  height_inc  provide  the  preferred 

*  increment  of  sizes  in  the  range  from  min_width 

*  to  max_width  and  min_height  to  max_height.  */ 

Errors 

BadWindow 
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XGetlconSizes  (continued)         Xlib  -  Window  Manager  Hints 

Related  Commands 

XAllocIconSize, XFetchName, XGetClassHint, XGetlconName, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints,  XGetZoom- 
Hints, XSetClassHint, XSetCommand, XSetlconSizes,  XSetNormalHints, 
XSetSizeHints, XSetTransientForHint, XSetWMHints,  XSetZoomHints, 
XStoreName . 
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Name 

XGetlmage  —  place  contents  of  a  rectangle  from  drawable  into  an  image. 

Synopsis 

Xlmage  * XGet Image ( display,  drawable,  x,  y,  width,  height, 

plan e_ma sk ,  forma t ) 
Display  * display; 
Drawable  drawable; 
int  x ,  y  ; 

unsigned  int  width,  height; 
unsigned  long  plane_mask; 
int  format; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawable         Specifies  the  drawable  to  get  the  data  from. 

x  Specify  the  x  and  y  coordinates  of  the  upper-left  corner  of  the  rectangle,  rela- 

y  live  to  the  origin  of  the  drawable. 

wi  dth  Specify  the  width  and  height  in  pixels  of  the  image. 

height 

plane_mask     Specifies  a  plane  mask  that  indicates  which  planes  are  represented  in  the 
image. 

format  Specifies  the  format  for  the  image.  Pass  either  XYPixmap  or  ZPixmap. 

Description 

XGetlmage  dumps  the  contents  of  the  specified  rectangle,  a  drawable,  into  a  client-side  Xlm 
age  structure,  in  the  format  you  specify.  Depending  on  which  format  you  pass  to  the  format 
argument,  the  function  does  the  following: 

If  the  format  is  XYP  ixmap 

Gets  only  the  bit  planes  you  passed  to  the  plane_mask  argument. 
•         If  the  format  is  ZP  ixmap 

Sets  to  0  the  bits  in  all  planes  not  specified  in  the  plane_mask  argument.  The  function 
performs  no  range  checking  on  the  values  in  plane_mask,  and  ignores  extraneous  bits. 

XGetlmage  returns  the  depth  of  the  image  to  the  depth  member  of  the  ximage  structure. 
This  depth  is  as  specified  when  the  drawable  was  created. 

If  the  drawable  is  a  pixmap,  the  specified  rectangle  must  be  completely  inside  the  pixmap,  or  a 
BadMatch  error  will  occur,  and  the  visual  field  in  the  image  will  be  None.  If  XGetlmage 
fails,  it  returns  NULL.  If  the  drawable  is  a  window,  the  window  must  be  viewable,  and  the  speci 
fied  rectangle  must  not  go  off  the  edge  of  the  screen.  Otherwise,  a  BadMatch  error  will  occur. 
If  the  drawable  is  a  window,  the  visual  argument  will  return  the  visual  specified  when  the 
drawable  was  created. 
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The  returned  image  will  include  any  visible  portions  of  inferiors  or  overlapping  windows  con 
tained  in  the  rectangle.  The  image  will  not  include  the  cursor.  The  specified  area  can  include 
the  borders.  The  returned  contents  of  visible  regions  of  inferiors  of  different  depth  than  the 
specified  window  are  undefined. 

If  the  window  has  a  backing-store,  the  backing-store  contents  are  returned  for  regions  of  the 
window  that  are  obscured  by  noninferior  windows.  Otherwise,  the  return  contents  of  such 
obscured  regions  are  undefined.  Also  undefined  are  the  returned  contents  of  visible  regions  of 
inferiors  of  different  depth  than  the  specified  window. 

The  data  in  the  image  structure  is  stored  in  the  server's  natural  byte-  and  bit-order. 
For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Errors 

BadDrawable 

BadMatch          See  Description  above. 

BadValue 

Related  Commands 

ImageByteOrder, XAddPixel, XCreatelmage, XDestroy Image,  XGetPixel, 
XGetSublmage, XPutlmage, XPutPixel, XSub Image. 
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—  Xllb -Input  Handling- 


J  XGetlnputFocus 


Name 

XGetlnputFocus  —  return  the  current  keyboard  focus  window. 

Synopsis 

XGetlnputFocus (display,  focus,    revert_to) 
Display    *display; 

window  *  focus;  /*  RETURN   */ 

int    *revert_to;  /*  RETURN    */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

focus  Returns  the  ID  of  the  focus  window,  or  one  of  the  constants  PointerRoot 

or  None. 

revert_to  Returns  the  window  to  which  the  focus  would  revert  if  the  focus  window 
became  invisible.  This  is  one  of  these  constants:  Re  vert  TOP  a  rent, 
RevertToPointerRoot,  or  RevertToNone.  Must  not  be  a  window  ID. 

Description 

XGetlnputFocus  returns  the  current  keyboard  focus  window  and  the  window  to  which  the 
focus  would  revert  if  the  focus  window  became  invisible. 

XGetlnputFocus  does  not  report  the  last  focus  change  time.  This  is  available  only  from 
Focus  In  and  FocusOut  events. 

Related  Commands 

QLength,  XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event,  XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetMotionEvents, Xlf Event, XMaskEvent,  XNextEvent,  XPeekEvent,  XPeek- 
If Event,  XPending, XPutBackEvent,  XSelectlnput,  XSendEvent,  XSetlnput- 
Focus, XSynchronize, XWindowEvent. 
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XGetKeyboardControl 


•Xlib  -  User  Preferences— 


Name 

XGetKeyboardControl  —  obtain  a  list  of  the  current  keyboard  preferences. 

Synopsis 

XGetKeyboardControl (display,  values) 
Display  *display; 
XKeyboardState  *values;   /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

values  Returns  filled  XKeyboardState  structure. 

Description 

XGetKeyboardControl  returns  the  current  control  values  for  the  keyboard.  For  the  LEDs 
(light  emitting  diodes),  the  least  significant  bit  of  led_jnask  corresponds  to  LED  1,  and  each 
bit  that  is  set  to  1  in  led_mask  indicates  an  LED  that  is  lit.  auto_repeats  is  a  bit  vector; 
each  bit  that  is  set  to  1  indicates  that  auto-repeat  is  enabled  for  the  corresponding  key.  The  vec 
tor  is  represented  as  32  bytes.  Byte  N  (from  0)  contains  the  bits  for  keys  8N  to  8N+7,  with  the 
least  significant  bit  in  the  byte  representing  key  8N.  global_auto_repeat  is  either 
AutoRepeatModeOn  or  AutoRepeatModeOf f . 

For  the  ranges  of  each  member  of  XKeyboardState,  see  the  description  of  XChange- 
PointerControl. 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
Structures 

typedef  struct  { 

int  key_click_percent; 

int  bell_percent; 

unsigned  int  bell_pitch,  bell_duration; 

unsigned  long  led_mask; 

int  global_auto_repeat ; 

char  auto_repeats [32] ; 
}  XKeyboardState; 

Related  Commands 

XAutoRepeatOf f , XAutoRepeatOn, XBell,  XChangeKeyboardControl, XGet- 
Def ault, XGetPointerControl. 
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—  Xlib- Keyboard 


/  XGetKeyboardMapping 


Name 

XGetKeyboardMapping  —  return  symbols  for  keycodes. 
Synopsis 

KeySym  *XGetKeyboardMapping ( display,  first_keycode, 

keycode_count ,  keysyms_per_keycode) 
Display  * display ; 
KeyCode  first_keycode; 
int  keycode_count ; 
int  *keysyms_per_keycode;  /*  RETURN  */ 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 
first_keycode 

Specifies  the  first  keycode  that  is  to  be  returned. 

keycode_count 

Specifies  the  number  of  keycodes  that  are  to  be  returned. 

£eysyms_per_.keycode 

Returns  the  number  of  keysyms  per  keycode. 

Description 

Starting  with  first_keycode,  XGetKeyboardMapping  returns  the  symbols  for  the 
specified  number  of  keycodes.  The  specified  first_keycode  must  be  greater  than  or  equal 
to  min_keycode  as  returned  by  XDisplayKeycodes,  otherwise  a  BadValue  error 
occurs.  In  addition,  the  following  expression  must  be  less  than  or  equal  to  max_keycode 
(also  returned  by  XDisplayKeycodes)  as  returned  in  the  Display  structure,  otherwise  a 
BadValue  error  occurs: 

first_keycode  +   keycode_count   -    1 
The  number  of  elements  in  the  keysyms  list  is: 

keycode_count  *  keysyms_per_keycode 

Then,  keysym  number  N  (counting  from  0)  for  keycode  K  has  an  index  (counting  from  0)  of  the 
following  (in  keysyms): 

(K   -    first_keycode)     *    keysyms_per_keycode   +   N 

The  keysyms_per_keycode  value  is  chosen  arbitrarily  by  the  server  to  be  large  enough  to 
report  all  requested  symbols.  A  special  KeySym  value  of  NoSymbol  is  used  to  fill  in  unused 
elements  for  individual  keycodes. 

Use  XFree  to  free  the  returned  keysym  list  when  you  no  longer  need  it. 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
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XGetKeyboardMapping  (continued)  Xlib  -  Keyboard 

Errors 

BadValue  first_keycode  less  than  display->min_keycode  . 

display->max_keycode  exceeded. 

Related  Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry,  XFreeModif iermap, 
XGetModif ierMapping, XInsertModif iermapEntry, XKeycodeToKeysym, 
XKeysymToKeycode, XKeysymToString, XLookupKeysym,  XLookupString, 
XNewModif  ierMap,  XQueryKeymap,  XRebindKeySym,  XRef reshKeyboard- 
Mapping,  XSetModif ierMapping, XStringToKeysym. 
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—X  Programming  Library- 


J  XGetModifierMapping 


Name 

XGetModifierMapping  —  obtain  a  mapping  of  modifier  keys  (Shift,  Control,  etc.). 
Synopsis 

XModifierKeymap  *XGetModif ierMapping (display) 
Display  *display; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

Description 

XGetModifierMapping  returns  the  keycodes  of  the  keys  being  used  as  modifiers. 

There  are  eight  modifiers,  represented  by  the  symbols  Shif  tMapindex,  LockMapindex, 
ControlMapIndex,  ModlMapIndex,  Mod2MapIndex,  ModSMapIndex,  Mod4Map- 
Index,  and  ModSMapIndex.  The  modif iermap  member  of  the  XModifierKeymap 
structure  contains  eight  sets  of  keycodes,  each  set  containing  max_keypermod  keycodes. 
Zero  keycodes  are  not  meaningful.  If  an  entire  modif  iermap  is  filled  with  zero's,  the  corre 
sponding  modifier  is  disabled.  No  keycode  will  appear  twice  anywhere  in  the  map. 

Structures 

typedef  struct  { 

int  max  keypermod;     /*  server's  max  number  of  keys  per  modifier  */ 
KeyCode  *modif iermap;  /*  an  8  by  max_keypermod  array  of 

*  keycodes  to  be  used  as  modifiers  */ 

}  XModifierKeymap; 

/*  modifier  names.   Used  to  build  a  SetModif ierMapping  request  or 

to  read  a  GetModif ierMapping  request.  */ 
#define  ShiftMapIndex     0 
#define  LockMapindex      1 

#define  ControlMapIndex  2 

#define  ModlMapIndex  3 
#define  Mod2MapIndex  4 
#define  ModSMapIndex  5 
tdefine  ModSMapIndex  6 
#define  ModSMapIndex  7 

Related  Commands 

XChangeKeyboardMapping,  XDeleteModifiermapEntry,  XFreeModif  iermap, 
XGetKeyboardMapping,  XInsertModif  iermapEntry,  XKeycodeToKeysym, 
XKeysymToKeycode, XKeysymToString, XLookupKeysym,  XLookupString, 
XNewModif  ierMap,  XQueryKeymap,  XRebindKeySym,  XRef reshKeyboard- 
Mapping,  XSetModif ierMapping, XStringToKeysym. 
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Name 

XGetMotionEvents  —  get  events  from  pointer  motion  history  buffer. 

Synopsis 

XTimeCoord  *XGetMotionEvents ( display,  w,  start,  stop,  nevents) 
Display  *display; 
Window  w; 
Time  start,  stop; 
int  *  nevents;  /*  RETURN  */ 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

vf  Specifies  the  ID  of  the  window  whose  associated  pointer  motion  events  will  be 

returned. 

start  Specify  the  time  interval  for  which  the  events  are  returned  from  the  motion  his- 

stop  tory  buffer.  Pass  a  time  stamp  (in  milliseconds)  or  Cur  rent  Time. 

nevents         Returns  the  number  of  events  returned  from  the  motion  history  buffer. 

Description 

XGetMotionEvents  returns  all  events  in  the  motion  history  buffer  that  fall  between  the 
specified  start  and  stop  times  (inclusive)  and  that  have  coordinates  that  lie  within  (including 
borders)  the  specified  window  at  its  present  placement.  The  x  and  y  coordinates  of  the 
XTimeCoord  return  structure  are  reported  relative  to  the  origin  of  w. 

XGetMotionEvent  returns  NULL  if  the  server  does  not  support  a  motion  history  buffer 
(which  is  common),  or  if  the  start  time  is  after  the  stop  time,  or  if  the  start  time  is  in  the  future. 
A  motion  history  buffer  is  supported  if  XDisplayMotionBuf  f  erSize  (display)  >  0.  The 
pointer  position  at  each  pointer  hardware  interrupt  is  then  stored  for  later  retrieval. 

If  the  start  time  is  later  than  the  stop  time,  or  if  the  start  time  is  in  the  future,  no  events  are 
returned.  If  the  stop  time  is  in  the  future,  it  is  equivalent  to  specifying  the  constant  Cur rent - 
Time,  since  the  server  does  not  wait  to  report  future  events. 

Use  XFree  to  free  the  returned  XTimeCoord  structures  when  they  are  no  longer  needed. 
For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 

Structures 

typedef  struct  _XTimeCoord  { 

Time  time; 

short    x,    y; 
}    XTimeCoord; 

Errors 

BadWindow 
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Related  Commands 

QLength, XAllowEvents, XChecklf Event,  XCheckMaskEvent,  XCheckTyped- 
Event,  XCheckTypedWindowEvent, XCheckWindowEvent,  XEventsQueued, 
XGetlnputFocus, Xlf Event, XMaskEvent,  XNextEvent,  XPeekEvent,  XPeek- 
If Event, XPending, XPutBackEvent, XSelectlnput,  XSendEvent,  XSetlnput- 
Focus, XSynchronize, XWindowEvent. 
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XGetNormalHints  V X1|b  _  Window  Manager  Hlms_ 

Name 

XGetNormalHints  —  get  the  size  hints  property  of  a  window  in  normal  state  (not  zoomed  or 
iconified). 

Synopsis 

Status  XGetNormalHints (display,  w,  hints) 
Display  *display; 
Window  w; 
XSizeHints  *hints;         /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  to  be  queried. 

hints  Returns  the  sizing  hints  for  the  window  in  its  normal  state. 

Description 

XGetNormalHints  has  been  superseded  by  XGetWMNormalHints  as  of  Release  4, 
because  new  interclient  communication  conventions  are  now  standard. 

XGetNormalHints  returns  the  size  hints  for  a  window  in  its  normal  state  by  reading  the 
XA_WM_NORMAL_HINTS  property.  This  function  is  normally  used  only  by  a  window  manager.  It 
returns  a  nonzero  Status  if  it  succeeds,  and  zero  if  it  fails  (e.g.,  the  application  specified  no 
normal  size  hints  for  this  window.) 

For  more  information  on  using  hints,  see  Volume  One,  Chapter  W, Interclient  Communication. 
Structures 

typedef  struct  { 

long  flags;    /*  which  fields  in  structure  are  defined  */ 

int  x,  y; 

int  width,  height; 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x;      /*  numerator  */ 

int  y;      /*  denominator  */ 
}  min_aspect,  max_aspect; 
}  XSizeHints; 

/*  flags  argument  in  size  hints  */ 

ttdefine  USPosition  (1L  «  O)/*  user  specified  x,  y  */ 

#define  USSize      (1L  «  I)/*  user  specified  width,  height  */ 

#define  PPosition  (1L  «  2)/*  program  specified  position  */ 

#define  PSize  (1L  «  3)/*  program  specified  size  */ 

#define  PMinSize  (1L  «  4)/*  program  specified  minimum  size  */ 

tdefine  PMaxSize  (1L  «  5)/*  program  specified  maximum  size  */ 
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tdefine  PResizelnc  (1L  «  6)/*  program  specified  resize  increments  */ 
#define  PAspect     (1L  «  7)/*  program  specified  min/max  aspect  ratios  */ 
#def ine  PAllHints  (PPosition | PSize I PMinSize I PMaxSize | PResizelnc I PAspect) 

Errors 

BadWindow 

Related  Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetSize- 
Hints,  XGetTransientForHint,  XGetWMHints,  XGetZoomHints,  XSetClass- 
Hint,  XSetCommand,  XSetlconName,  XSetlconSizes,  XSetNormalHints, XSet- 
SizeHints,  XSetTransientForHint, XSetWMHints,  XSetZoomHints, XStore- 
Name. 
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XGetPixel 


\ 


-Xlib-  Images- 


Name 

XGetPixel  —  obtain  a  single  pixel  value  from  an  image. 

Synopsis 

unsigned  long  XGetPixel  (ximage,  x,  y) 
Xlmage  * ximage; 
int  x; 
int  y; 


Arguments 

ximage 

x 

y 


Specifies  a  pointer  to  the  image. 

Specify  the  x  and  y  coordinates  of  the  pixel  whose  value  is  to  be  returned. 


Description 

XGetPixel  returns  the  specified  pixel  from  the  named  image.  The  x  and  y  coordinates  are 
relative  to  the  origin  (upper  left  [0,0])  of  the  image).  The  pixel  value  is  returned  in  the  clients 
bit-  and  byte-order.  The  x  and  y  coordinates  must  be  contained  in  the  image. 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 


Structures 

typedef  struct  _XImage  { 
int  width,  height; 
int  xoffset; 
int  format; 
char  *data; 
int  byte_order; 
int  bitmap_unit; 
int  bitmap  bit  order; 
int  bitmap_pad; 
int  depth; 
int  bytes_per_line; 
int  bits_per_pixel; 
unsigned  long  red_mask; 
unsigned  long  green_mask; 
unsigned  long  blue  mask; 
char  *obdata; 
struct  funcs  { 

struct  _XImage  *  (*create_image)  ()  ; 

int  (*destroy_image) () ; 

unsigned  long  (*get_pixel) () ; 

int  (*put_pixel) () ; 

struct  _XImage  *  (*sub_image)  ()  ; 

int  (*add_pixel) () ; 
}  f; 
}  Ximage; 


size  of  image  */ 

number  of  pixels  offset  in  X  direction  */ 


/*  XYBitmap,  XYPixmap,  ZPixmap  */ 


pointer  to  image  data  */ 

data  byte  order,  LSBFirst,  MSBFirst  */ 

quant,  of  scan  line  8,  16,  32  */ 

LSBFirst,  MSBFirst  */ 

8,  16,  32  either  XY  or  ZPixmap  */ 

depth  of  image  */ 

accelerator  to  next  line  */ 

bits  per  pixel  (ZPixmap)  */ 

bits  in  z  arrangment  */ 


/*  hook  for  the  object  routines  to  hang  on 
/*  image  manipulation  routines  */ 
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Related  Commands 

ImageByteOrder,  XAddPixel,  XCreate Image,  XDestroy Image,  XGetlmage, 
XGetSublmage,  XPutlmage,  XPutPixel,  XSublmage. 
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XGetPointerControl  "\ 


Xlib- Pointer- 


Name 

XGetPointerControl  —  get  the  current  pointer  preferences. 

Synopsis 

XGetPointerControl (display,  accel_numerator,  accel_denominator , 

threshold) 
Display  *  display ; 

int  *accel_numeratorf  *accel_denominator;   /*  RETURN  */ 
int  *  threshold;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

accel_numerator 

Returns  the  numerator  for  the  acceleration  multiplier. 

accel_denominator 

Returns  the  denominator  for  the  acceleration  multiplier. 

threshold       Returns  the  acceleration  threshold  in  pixels.  The  pointer  must  move  more 
than  this  amount  before  acceleration  takes  effect. 

Description 

XGetPointerControl  gets  the  pointer  acceleration  parameters. 

accel_numerator  divided  by  accel_denominator  is  the  number  of  pixels  the  cursor 
moves  per  unit  of  motion  of  the  pointer,  applied  only  to  the  amount  of  movement  over 
threshold. 

Related  Commands 

XChangeActivePointerGrab, XChangePointerControl, XGetPointer- 
Mapping, XGrabPointer, XQueryPointer,  XSetPointerMapping, XUngrab- 
Pointer,  XWarpPointer. 
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J  XGetPointerMapping 


Name 

XGetPointerMapping  —  get  the  pointer  button  mapping. 

Synopsis 

int  XGetPointerMapping ( display,  map,  nmap) 
Display  *  display; 

unsigned  char  map  [  ]  ;       /*  RETURN  */ 
int  nmap ; 

Arguments 

di spl ay         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

map  Returns  the  mapping  list.  Array  begins  with  map  [  ] . 

nmap  Specifies  the  number  of  items  in  mapping  list. 

Description 

XGetPointerMapping  returns  the  current  mapping  of  the  pointer  buttons.  Information  is 
returned  in  both  the  arguments  and  the  function's  return  value,  map  is  an  array  of  the  numbers 
of  the  buttons  as  they  are  currently  mapped.  Elements  of  the  list  are  indexed  starting  from  1. 
The  nominal  mapping  for  a  pointer  is  the  identity  mapping:  map[i]=i.  If  map  [3]  =2,  it 
means  that  the  third  physical  button  triggers  the  second  logical  button. 

nmap  indicates  the  desired  number  of  button  mappings. 

The  return  value  of  the  function  is  the  actual  number  of  elements  in  the  pointer  list,  which  may 
be  greater  or  less  than  nmap. 

Related  Commands 

XChangeActivePointerGrab, XChangePointerControl,  XGetPointer- 
Control, XGrabPointer, XQueryPointer,  XSetPointerMapping, XUngrab- 
Pointer, XWarpPointer. 
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XGetRGBColOrmapS  \ x,,b-W,ndow  Manages- 

Name 

XGetRGBColormaps  —  obtain  the  XStandardColormap  structure  associated  with  the 
specified  property. 

Synopsis 

Status  XGetRGBColormaps ( display,  w,  std_colormap,  count, 

property) 
Display  *display; 
Window  w; 

XStandardColormap  **std_col ormap;     /*  RETURN  */ 
int  *  count;  /*  RETURN  */ 

Atom  property; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window. 

std_col ormap 

Returns  the  XStandardColormap  structure. 

count  Returns  the  number  of  colormaps . 

property         Specifies  the  property  name. 

Availability 

Release  4  and  later. 

Description 

XGetRGBColormaps  returns  the  RGB  colormap  definitions  stored  in  the  specified  property 
on  the  named  window.  If  the  property  exists,  is  of  type  RGB_COLOR_MAP  ,  is  of  format  32,  and  is 
long  enough  to  contain  a  colormap  definition,  XGetRGBColormaps  allocates  and  fills  in 
space  for  the  returned  colormaps,  and  returns  a  non-zero  status.  Otherwise,  none  of  the  fields 
are  set,  and  XGetRGBColormaps  returns  a  zero  status.  If  the  visualid  field  is  not  present, 
XGetRGBColormaps  assumes  the  default  visual  for  the  screen  on  which  the  window  is 
located;  if  the  killid  field  is  not  present,  it  is  assumed  to  have  a  value  of  None,  which  indicates 
that  the  resources  cannot  be  released.  Note  that  it  is  the  caller's  responsibility  to  honor  the 
ICCCM  restriction  that  only  RGB_DEFAULT_MAP  contain  more  than  one  definition. 

XGetRGBColormaps  supersedes  XGetStandardColormap. 
For  more  information,  see  Volume  One,  Chapter  7,  Color. 

Structures 

typedef  struct  { 

Colormap  colormap; 
unsigned  long  red_max; 
unsigned  long  red_mult; 
unsigned  long  green  max; 
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unsigned  long  green_mult; 
unsigned  long  blue_max; 
unsigned  long  blue_mult; 
unsigned  long  base_pixel; 

VisuallD  visualid;  /*  added  by  ICCCM  version  1  */ 

XID  killid;  /*  added  by  ICCCM  version  1  */ 

}  XStandardColormap; 

Errors 

BadAtom 
BadWindow 

Related  Commands 

XAllocStandardColormap, XSetRGBColormaps. 
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XGetScreenSaver  \. 


•Xllb  -  Screen  Saver— 


Name 

XGetScreenSaver  —  get  the  current  screen  saver  parameters. 

Synopsis 

XGetScreenSaver ( display,    timeout,    interval,    prefer_blanking, 

allow_exposures) 
Display   * display; 

int    *timeout,    *  interval ;       /*  RETURN    */ 
int    *prefer_blanking;  /*  RETURN    */ 

int    *allow_exposures;  /*  RETURN    */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

timeout  Returns  the  idle  time,  in  seconds,  until  the  screen  saver  turns  on. 

interval          Returns  the  interval  between  screen  changes,  in  seconds. 

prefer_blanking 

Returns  the  current  screen  blanking  preference,  one  of  these  constants: 
DontPref erBlanking, Pref erBlanking,  or  Def aultBlanking. 

allotvr_exposures 

Returns    the    current    screen    save   control    value,    either    DontAl low- 
Exposures,  AllowExposures,  or  Def aultExposures. 

Description 

XGetScreenSaver  returns  the  current  settings  of  the  screen  saver,  which  may  be  set  with 

XSet ScreenSaver. 

A  positive  timeout  indicates  that  the  screen  saver  is  enabled.  A  timeout  of  zero  indicates 
that  the  screen  saver  is  disabled. 

If  the  server-dependent  screen  saver  method  supports  periodic  change,  interval  serves  as  a 
hint  about  the  length  of  the  change  period,  and  zero  serves  as  a  hint  that  no  periodic  change 
will  be  made.  An  interval  of  zero  indicates  that  random  pattern  motion  is  disabled. 

For  more  information  on  the  screen  saver,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 

Related  Commands 

XActivateScreenSaver, XForceScreenSaver, XResetScreenSaver, XSet- 
ScreenSaver. 
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J  XGetSelectionOwner 


Name 

XGetSelectionOwner  —  return  the  owner  of  a  selection. 

Synopsis 

Window  XGetSelectionOwner ( display,  selection) 
Display  * display; 
Atom  selection; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

select i  on        Specifies  the  selection  atom  whose  owner  you  want  returned. 
Description 

XGetSelectionOwner  returns  the  window  ID  of  the  current  owner  of  the  specified  selec 
tion.  If  no  selection  was  specified,  or  there  is  no  owner,  the  function  returns  the  constant  None, 

For  more  information  on  selections,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Errors 

BadAtom 

Related  Commands 

XConvert Select ion, XSet Select ionOwner. 
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X,,b-W,ndowManager  «,„«,- 

Name 

XGetSizeHintS  —  read  any  property  of  type  XA_SIZE_HINTS. 

Synopsis 

Status  XGetSizeHintS ( display,  w,  hints,  property) 
Display  *display; 
Window  w; 

XSizeHints  *hints;         /*  RETURN  */ 
Atom  property; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD i  sp  1  ay . 

w  Specifies  the  ID  of  the  window  for  which  size  hints  will  be  returned. 

hints  Returns  the  size  hints  structure. 

property  Specifies  a  property  atom  of  type  XA_WM_SIZE_HINTS.  May  be 
XA_WM_NORMAL_HINTS,  XA_WM_ZOOM_HINTS  (in  Release  3),  or  a  property 
defined  by  an  application. 

Description 

XGetSizeHintS  has  been  superseded  by  XGetWMSizeHints  as  of  Release  4,  because  the 
interclient  communication  conventions  are  now  standard. 

XGetSizeHintS  returns  the  XSizeHints  structure  for  the  named  property  and  the  speci 
fied  window.  This  is  used  by  XGetNormalHints  and  XGetZoomHints,  and  can  be  used  to 
retrieve  the  value  of  any  property  of  type  XA_WM_SIZE_HINTS;  thus,  it  is  useful  if  other  proper 
ties  of  that  type  get  defined.  This  function  is  used  almost  exclusively  by  window  managers. 

XGetSizeHintS  returns  a  nonzero  Status  if  a  size  hint  was  defined,  and  zero  otherwise. 
For  more  information  on  using  hints,  see  Volume  One,  Chapter  10, Interclient  Communication. 

Structures 

typedef  struct  { 

long  flags;     /*  which  fields  in  structure  are  defined  */ 

int  x,  y; 

int  width,  height; 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x;      /*  numerator  */ 

int  y;      /*  denominator  */ 
}  min_aspect,  max_aspect; 
}  XSizeHints; 

/*  flags  argument  in  size  hints  */ 

#define  USPosition  (1L  «  0)  /*  user  specified  x,  y  */ 

#define  USSize      (1L  «  1)  /*  user  specified  width,  height  */ 
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(continued) 


XGetSizeHints 


#define  PPosition   (1L  «  2)  /*  program  specified  position  */ 


#define  PSize  (1L  «  3)  A 

tdefine  PMinSize  (1L  «  4)  /' 

#define  PMaxSize  (1L  «  5)  /' 

tfdefine  PResizelnc  (1L  «  6)  /' 

#define  PAspect  (1L  «  7)  /' 


program  specified  size  */ 
program  specified  minimum  size  */ 
program  specified  maximum  size  */ 
program  specified  resize  increments  */ 
program  specified  min/max  aspect  ratios  */ 


tdefine  PAllHints  (PPosition | PSize I PMinSize I PMaxSize I PResizelnc I PAspect) 

Errors 

BadAtom 
BadWindow 

Related  Commands 

XFetchName, XGetClassHint, XGetlconName,  XGetlconSizes, XGetNormal- 
Hints,  XGetTransientForHint, XGetWMHints, XGetZoomHints, XSetClass- 
Hint, XSet Command,  XSetlconName, XSetlconSizes,  XSetNormalHints, XSet- 
SizeHints, XSetTransientForHint, XSetWMHints,  XSetZoomHints,  XStore- 
Name. 
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XGetStandardColormap  \ X1|b  _  Colormaps_ 

Name 

XGetStandardColormap  —  get  the  standard  colormap  property. 

Synopsis 

Status  XGetStandardColormap ( display,  w,  cmap_info,  property) 
Display  * display; 
Window  w; 

XStandardColormap  *cmap_info; /*  RETURN  */ 
Atom  property; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD  i  sp  1  ay . 

w  Specifies  the  ID  of  the  window  on  which  the  property  is  set.  This  is  normally 

the  root  window. 

cmap_info       Returns  the  filled  colormap  information  structure. 

property         Specifies  the  atom  indicating  the  type  of  standard  colormap  desired.  The 
predefined       standard       colormap       atoms       are       XA_RGB_BEST_MAP, 

XA_RGB_RED_MAP,       XA_RGB_GREEN_MAP,       XA_RGB_BLUE_MAP , 
XA_RGB_DEFAULT_MAP,  and  XA_RGB_GRAY_MAP . 

Description 

XGetStandardColormap  is  superseded  by  XGetWMColormap  in  Release  4. 

XGetStandardColormap  gets  a  property  on  the  root  window  that  describes  a  standard 
colormap. 

This  call  does  not  install  the  colormap  into  the  hardware  colormap,  it  does  not  allocate  entries, 
and  it  does  not  even  create  a  virtual  colormap.  It  just  provides  information  about  one  design  of 
colormap  and  the  ID  of  the  colormap  if  some  other  client  has  already  created  it.  The  applica 
tion  can  otherwise  attempt  to  create  a  virtual  colormap  of  the  appropriate  type,  and  allocate  its 
entries  according  to  the  information  in  the  XStandardColormap  structure.  Installing  the 
colormap  must  then  be  done  with  XlnstallColormap,  in  cooperation  with  the  window 
manager.  Any  of  these  steps  could  fail,  and  the  application  should  be  prepared. 

If  the  server  or  another  client  has  already  created  a  standard  colormap  of  this  type,  then  its  ID 
will  be  returned  in  the  colormap  member  of  the  XStandardColormap  structure.  Some 
servers  and  window  managers,  particular  on  high-performance  workstations,  will  create  some 
or  all  of  the  standard  colormaps  so  they  can  be  quickly  installed  when  needed  by  applications. 

An  application  should  go  through  the  standard  colormap  creation  process  only  if  it  needs  the 
special  qualities  of  the  standard  colormaps.  For  one,  they  allow  the  application  to  convert  RGB 
values  into  pixel  values  quickly  because  the  mapping  is  predictable.  Given  an  XStandard 
Colormap  structure  for  an  XA_RGB_BEST_MAP  colormap,  and  floating  point  RGB  coefficients 
in  the  range  0.0  to  1.0,  you  can  compose  pixel  values  with  the  following  C  expression: 
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pixel  =  base_pixel 

+  ((unsigned  long)  (0.5  +  r  *  red_max) )  *  red_mult 

+  ((unsigned  long)  (0.5  +  g  *  green_max) )  *  greenjmult 

+  ((unsigned  long)  (0.5  +  b  *  blue_max) )  *  blue_mult; 

The  use  of  addition  rather  than  logical-OR  for  composing  pixel  values  permits  allocations 
where  the  RGB  value  is  not  aligned  to  bit  boundaries. 

XGetStandardColormap  returns  zero  if  it  fails,  or  nonzero  if  it  succeeds. 

See  Volume  One,  Chapter  7,  Color,  for  a  complete  description  of  standard  coiormaps. 

Structures 

typedef  struct  { 

Colormap  colormap;    /*  ID  of  colormap  created  by  XCreateColormap  */ 

unsigned  long  red_max; 

unsigned  long  red_mult; 

unsigned  long  green_max; 

unsigned  long  green_mult; 

unsigned  long  blue_max; 

unsigned  long  blue_mult; 

unsigned  long  base_pixel; 

/*  new  fields  here  in  R4  */ 
}  XStandardColormap; 

Errors 

BadAtom 
BadWindow 

Related  Commands 

Def  aultColormap,  Display-Cells,  XCopyColormapAndFree,  XCreate 
Colormap,  XFreeColormap, XInstallColormap,  XListlnstalledColormaps, 
XSetStandardColormap,  XSetWindowColormap,  XUninstallColormap. 
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XGetSublmage  \ xnt>.tmages- 

Name 

XGetSublmage  —  copy  a  rectangle  in  drawable  to  a  location  within  the  pre-existing  image. 
Synopsis 

Xlmage  *XGetSubImage ( display,  drawable ,  x,  y,  width,  height, 

plane_mask,  format,  dest_image,  dest_x,  dest_y) 
Display  * display; 
Drawable  drawable; 
int  x,  y; 

unsigned  int  width,  height; 
unsigned  long  plane_mask; 
int  format; 
Xlmage  *dest_image; 
int  dest_x,  dest_y; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawabl  e         Specifies  the  drawable  from  which  the  rectangle  is  to  be  copied. 

x  Specify  the  x  and  y  coordinates  of  the  upper-left  corner  of  the  rectangle,  rela- 

y  live  to  the  origin  of  the  drawable. 

width  Specify  the  width  and  height  in  pixels  of  the  subimage  taken. 

height 

plane_mask     Specifies  which  planes  of  the  drawable  are  transferred  to  the  image. 
format  Specifies  the  format  for  the  image.  Either  XYPixmap  or  ZPixmap. 

dest_image     Specifies  the  the  destination  image. 

dest_x  Specify  the  x  and  y  coordinates  of  the  destination  rectangle's  upper  left  cor- 

dest_y  ner,  relative  to  the  image's  origin. 

Description 

XGetSublmage  updates  the  dest_image  with  the  specified  subimage  in  the  same  manner 
as  XGet  image,  except  that  it  does  not  create  the  image  or  necessarily  fill  the  entire  image.  If 
format  is  XYPixmap,  the  function  transmits  only  the  bit  planes  you  specify  in 
plane_mask.  If  format  is  ZPixmap,  the  function  transmits  as  zero  the  bits  in  all  planes 
not  specified  in  plane_mask.  The  function  performs  no  range  checking  on  the  values  in 
plane_mask  and  ignores  extraneous  bits. 

The  depth  of  the  destination  x  image  structure  must  be  the  same  as  that  of  the  drawable. 
Otherwise,  a  BadMatch  error  is  generated.  If  the  specified  subimage  does  not  fit  at  the  speci 
fied  location  on  the  destination  image,  the  right  and  bottom  edges  are  clipped.  If  the  drawable 
is  a  window,  the  window  must  be  mapped  or  held  in  backing  store,  and  it  must  be  the  case  that, 
if  there  were  no  inferiors  or  overlapping  windows,  the  specified  rectangle  of  the  window  would 
be  fully  visible  on  the  screen.  Otherwise,  a  BadMatch  error  is  generated. 
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If  the  window  has  a  backing  store,  the  backing  store  contents  are  returned  for  regions  of  the 
window  that  are  obscured  by  noninferior  windows.  Otherwise,  the  return  contents  of  such 
obscured  regions  are  undefined.  Also  undefined  are  the  returned  contents  of  visible  regions  of 
inferiors  of  different  depth  than  the  specified  window. 

XSub Image  extracts  a  subimage  from  an  image,  instead  of  from  a  drawable  like  XGetSub 
lmage. 

For  more  information  on  images,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Errors 

BadDrawable 

BadMatch          Depth  of  dest_i/nage  is  not  the  same  as  depth  of  drawable. 
BadValue 

Related  Commands 

ImageByteOrder,  XAddPixel,  XCreate Image,  XDestroy Image,  XGet  Image, 
XGetPixel, XPutlmage, XPutPixel, XSublmage. 
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XGetTeXtPrOperty  \ x,,b-W,ndow Manager  H,n,s- 

Name 

XGetTextProperty  —  read  one  of  a  window's  text  properties. 

Synopsis 

Status  XGetTextProperty  ( display,  wr  text_propf  property) 
Display  ^display; 
Window  w; 

XTextProperty  *text_prop;      /*  RETURN  */ 
Atom  property; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

w  Specifies  the  window. 

text_prop        Returns  the  XTextProperty  structure. 

property         Specifies  the  property  name. 

Availability 

Release  4  and  later. 

Description 

XGetTextProperty  reads  the  specified  property  from  the  window  and  stores  the  data  in  the 
returned  XTextProperty  structure.  It  stores  the  data  in  the  value  field,  the  type  of  the  data 
in  the  encoding  field,  the  format  of  the  data  in  the  format  field,  and  the  number  of  items  of 
data  in  the  nit  ems  field.  The  particular  interpretation  of  the  property's  encoding  and  data  as 
"text"  is  left  to  the  calling  application.  If  the  specified  property  does  not  exist  on  the  window, 
XGetTextProperty  sets  the  value  field  to  NULL,  the  encoding  field  to  None,  the  format 
field  to  zero,  and  the  nit  ems  field  to  zero. 

If  it  was  able  to  set  these  files  in  the  XTextProperty  structure,  XGetTextProperty 
returns  a  non-zero  status;  otherwise,  it  returns  a  zero  status. 

For  more  information,  see  Volume  One,  Chapter  10,  Interclient  Communication. 
Structures 

typedef  struct  { 

unsigned  char  *value;  /*  same  as  Property  routines  */ 

Atom  encoding;  /*  prop  type  */ 

int  format;  /*  prop  data  format:  8,  16,  or  32  */ 

unsigned  long  nitems;  /*  number  of  data  items  in  value  */ 
}  XTextProperty; 

Errors 

BadAtom 
BadWindow 
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Related  Commands 

XFreeStringList, XSetTextProperty,  XStringListToTextProperty,  XText- 
PropertytoStringList. 
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XGetTransientForHint 


Name 

XGetTransientForHint  —  get  the  XA_WM_TRANSIENT_FOR  property  of  a  window. 

Synopsis 

Status  XGetTransientForHint  (  display,  w,  prop_window) 
Display  *  display; 
Window  w; 
Window  *prop_nrindow;       /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi  splay. 

w  Specifies  the  ID  of  the  window  to  be  queried. 

prop_window  Returns  the  window  contained  in  the  XA_WM_TRANSIENT_FOR  property  of  the 
specified  window. 

Description 

XGetTransientForHint  obtains  the  XA_WM_TRANSIENT_FOR  property  for  the  specified 
window.  This  function  is  normally  used  by  a  window  manager.  This  property  should  be  set  for 
windows  that  are  to  appear  only  temporarily  on  the  screen,  such  as  pop-up  dialog  boxes.  The 
window  returned  is  the  main  window  to  which  this  popup  window  is  related.  This  lets  the  win 
dow  manager  decorate  the  popup  window  appropriately. 

XGetTransientForHint  returns  a  Status  of  zero  on  failure,  and  nonzero  on  success. 
For  more  information  on  using  hints,  see  Volume  One,  Chapter  W,Interclient  Communication. 

Errors 

BadWindow 

Related  Commands 

XFetchName,  XGetClassHint,  XGetlconName,  XGetlconSizes,  XGetNormal- 
Hints,  XGetSizeHints,  XGetWMHints,  XGetZoomHints,  XSetClassHint,  XSet- 
Command,  XSetlconName,  XSetlconSizes,  XSetNormalHints,  XSetSizeHints, 
XSetTransientForHint,  XSetWMHints,  XSetZoomHints,  XStoreName. 
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Name 

XGetVisuallnfo  —  find  the  visual  information  structures  that  match  the  specified  template. 

Synopsis 

XVisuallnfo  *XGetVisualInfo ( display,  vinfo_mask, 

vinfo_template,  nitems) 
Display  * display ; 
long  vinfo_mask; 
XVisuallnfo  *vinfo_template; 
int  *  nitems;  /*  RETURN  */ 

Arguments 

di splay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

vinfo_mask     Specifies  the  visual  mask  value.  Indicates  which  elements  in  template  are  to 
be  matched. 

vi  n  f  o_  t  empl  a  t  e 

Specifies  the  visual  attributes  that  are  to  be  used  in  matching  the  visual  struc 
tures. 

nitems  Returns  the  number  of  matching  visual  structures. 

Description 

XGetVisuallnfo  returns  a  list  of  visual  structures  that  describe  visuals  supported  by  the 
server  and  that  match  the  attributes  specified  by  the  vinfo_ template  argument.  If  no 
visual  structures  match  the  template,  XGetVisuallnfo  returns  a  NULL.  To  free  the  data 
returned  by  this  function,  use  XFree. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 
Structures 

typedef  struct  { 

Visual  *visuai; 

VisuallD  visualid; 

int  screen; 

unsigned  int  depth; 

int  class; 

unsigned  long  red_mask; 

unsigned  long  green_mask; 

unsigned  long  blue_mask; 

int  colormap_size; 

int  bits_per_rgb; 
}  XVisuallnfo"; 

/*  The  symbols  for  the  vinfo_mask  argument  are:  */ 

tdefine  VisualNoMask  0x0 

#define  VisuallDMask  Oxl 

tfdefine  VisualScreenMask  0x2 
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#define  VisualDepthMask  0x4 

#define  VisualClassMask  0x8 

#define  VisualRedMaskMask  0x10 

tdefine  VisualGreenMaskMask  0x20 

#define  VisualBlueMaskMask  0x40 

#define  VisualColormapSizeMask  0x80 

#define  VisualBitsPerRGBMask  0x100 

tdefine  VisualAllMask  OxlFF 

Related  Commands 

Def aultVisual, XVisuallDFromVisual, XMatchVisuallnf o, XListDepths. 
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Name 

XGetWMIconName  —  read  a  window's  XA_WM_ICON_NAME  property. 

Synopsis 

Status  XGetWMIconName  ( display,  w,  text_prop) 
Display  *display; 
Window  w; 
XTextProperty  *text_prop;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

w  Specifies  the  window. 

text_prop       Returns  the  XTextProperty  structure. 

Availability 

Release  4  and  later. 

Description 

XGetWMIconName  performs  an  XGet  Text  Property  on  the  XA_WM_ICON_NAME  property 
of  the  specified  window.  XGetWMIconName  supersedes  XGetlconName. 

This  function  is  primarily  used  by  window  managers  to  get  the  name  to  be  written  in  a  win 
dow's  icon  when  they  need  to  display  that  icon. 

For  more  information,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Structures 

typedef  struct  { 

unsigned  char  *value;  /*  same  as  Property  routines  */ 

Atom  encoding;  /*  prop  type  */ 

int  format;  /*  prop  data  format:  8,  16,  or  32  */ 

unsigned  long  nitems;  /*  number  of  data  items  in  value  */ 
}  XTextProperty; 

Related  Commands 

XGetWMName,  XSetWMIconName,  XSetWMName,  XSetWMProperties. 
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v Xlib  -  Window  Manager  Hints- 
Name 

XGetWMName  —  read  a  window's  XA_WM_NAME  property. 

Synopsis 

Status  XGetWMName  ( display  r  w,  text_prop) 
Display  *  display; 
Window  w; 
XTextProperty  *text_prop; /*  RETURN  */ 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD i splay. 

w  Specifies  the  window. 

text_prop       Returns  the  XTextProperty  structure. 

Availability 

Release  4  and  later. 

Description 

XGetWMName  performs  an  XGetTextProperty  on  the  XA_WM_NAME  property  of  the  speci 
fied  window.  XGetWMName  supersedes  XFetchName. 

XGetWMName  returns  nonzero  if  it  succeeds,  and  zero  if  the  property  has  not  been  set  for  the 
argument  window. 

For  more  information,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Structures 

typedef  struct  { 

unsigned  char  *value;  /*  same  as  Property  routines  */ 

Atom  encoding;  /*  prop  type  */ 

int  format;  /*  prop  data  format:  8,  16,  or  32  */ 

unsigned  long  nitems;  /*  number  of  data  items  in  value  */ 
}  XTextProperty; 

Related  Commands 

XGetWMIconName,  XSetWMIconName,  XSetWMName,  XSetWMProperties. 
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-XHb-WindowManager  Hints '  XGetWMNormalHintS 

Name 

XGetWMNormalHintS  —  read  a  window's  XA_WM_NORMAL_HINTS  property. 

Synopsis 

Status  XGetWMNormalHintS (display,  w,  hints,  supplied) 
Display  *display; 
Window  w; 

XSizeHints  *hints;/*  RETURN  */ 
long  * supplied; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window. 

hints  Returns  the  size  hints  for  the  window  in  its  normal  state. 

supplied  Returns  the  hints  that  were  supplied  by  the  user. 

Availability 

Release  4  and  later. 

Description 

XGetWMNormalHintS  returns  the  size  hints  stored  in  the  XA_WM_NORMAL_HINTS  property  on 
the  specified  window.  If  the  property  is  of  type  XA_WM_SIZE_HINTS,  of  format  32,  and  is  long 
enough  to  contain  either  an  old  (pre-ICCCM)  or  new  size  hints  structure,  XGetWMNormal 
HintS  sets  the  various  fields  of  the  XSizeHints  structure,  sets  the  supplied  argument  to 
the  list  of  fields  that  were  supplied  by  the  user  (whether  or  not  they  contained  defined  values) 
and  returns  a  non-zero  status.  XGetWMNormalHintS  returns  a  zero  status  if  the  application 
specified  no  normal  size  hints  for  this  window. 

XGetWMNormalHintS  supersedes  XGetNormalHints. 

If  XGetWMNormalHintS  returns  successfully  and  a  pre-ICCCM  size  hints  property  is  read, 
the  supplied  argument  will  contain  the  following  bits: 

(USPosition|USSize|PPosition|PSize|PMinSize|    PMaxSize I PResizelnc I PAspect) 

If  the  property  is  large  enough  to  contain  the  base  size  and  window  gravity  fields  as  well,  the 
supplied  argument  will  also  contain  the  following  bits: 

(PBaseSize | PWinGravity) 

This  function  is  normally  used  only  by  a  window  manager. 

For  more  information,  see  Volume  One,  Chapter  lOJnterclient  Communication. 

Structures 

typedef  struct  { 

long  flags;     /*  marks  which  fields  in  this  structure  are  defined  */ 
int  x,  y;       /*  obsolete  for  new  window  mgrs,  but  clients  */ 
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int   width,    height;         /*    should   set    so   old  wm' s   don't   mess   up    */ 
int   min_width,    min_height; 
int   max_width,    max_height; 
int   width_inc,    height_inc; 
struct    { 

int   x;      /*   numerator    */ 

int   y;      /*    denominator    */ 
}    min_aspect,    max_aspect; 

int   base_width,    base_height;  /*    added  by    ICCCM  version    I    */ 

int   win_gravity;  /*    added  by    ICCCM 

version    1    */ 
}    XSizeHints; 

Errors 

BadWindow 

Related  Commands 

XAllocSizeHints,    XGetWMSizeHints,    XSetWMNormalHints,    XSet- 
WMProperties, XSetWMSizeHints. 
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-Xllb-  Window  Manager  Hints /  XGetWMSizeHintS 

Name 

XGetWMSizeHintS  — read  a  window's  XA_WM_SIZE_HINTS  property. 

Synopsis 

Status  XGetWMSizeHintS (display,  w,  hints,  supplied,  property) 
Display  * display; 
Window  w; 

XSizeHints  *hints;  /*  RETURN  */ 

long  * supplied;  /*RETURN  */ 

Atom  property; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  window. 

hints  Returns  the  XSizeHints  structure. 

supplied  Returns  the  hints  that  were  supplied  by  the  user. 

property  Specifies  the  property  name. 

Availability 

Release  4  and  later. 

Description 

XGetWMSizeHintS  returns  the  size  hints  stored  in  the  specified  property  on  the  named  win 
dow.  If  the  property  is  of  type  XA_WM_SIZE_HINTS,  of  format  32,  and  is  long  enough  to  con 
tain  either  an  old  (pre-ICCCM)  or  new  size  hints  structure,  XGetWMSizeHintS  sets  the  vari 
ous  fields  of  the  XSizeHints  structure,  sets  the  supplied  argument  to  the  list  of  fields  that 
were  supplied  by  the  user  (whether  or  not  they  contained  defined  values),  and  returns  a  non 
zero  status.  If  the  hint  was  not  set,  it  returns  a  zero  status.  To  get  a  window's  normal  size  hints, 
you  can  use  the  XGetWMNormalHints  function  instead. 

XGetWMSizeHintS  supersedes  XGetSizeHints. 

If  XGetWMSizeHintS  returns  successfully  and  a  pre-ICCCM  size  hints  property  is  read,  the 
supplied  argument  will  contain  the  following  bits: 

(USPosition I USSize IPPosition I P Size IPMinSize I  PMaxSize I PResizelnc I P Aspect) 

If  the  property  is  large  enough  to  contain  the  base  size  and  window  gravity  fields  as  well,  the 
supplied  argument  will  also  contain  the  following  bits: 

(PBaseSize I PWinGravity) 

This  function  is  used  almost  exclusively  by  window  managers. 

For  more  information,  see  Volume  One,  Chapter  W,Interclient  Communication. 
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Structures 

typedef  struct  { 

long  flags;      /*  marks  which  fields  in  this  structure  are  defined  */ 

int  x,  y;        /*  obsolete  for  new  window  mgrs,  but  clients  */ 

int  width,  height;    /*  should  set  so  old  wm' s  don't  mess  up  */ 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x;   /*  numerator  */ 

int  y;   /*  denominator  */ 
}  min_aspect,  max_aspect; 

int  base_width,  base_height;  /*  added  by  ICCCM  version  1  */ 

int  win_gravity;  /*  added  by  ICCCM  version  1  */ 

}  XSizeHints; 

Errors 

BadAtom 
BadWindow 

Related  Commands 

XAllocSizeHints,  XGetWMNormalHints,  XSetWMNormalHints,  XSetWMSize- 
Hints. 
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XGetWindowAtlributes 


Name 

XGetWindow  Attributes  —  obtain  the  current  attributes  of  window. 
Synopsis 

Status  XGetWindowAt  tributes  (display,  w,  window_attributes) 
Display  *display; 
Window  w; 
XWindowAttributes  *window_attributes  ;  /*  RETURN  */ 

Arguments 

di  spl  ay         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  whose  current  attributes  you  want. 

window_at  tributes 

Returns  a  filled  XWindowAttributes  structure,  containing  the  current  attri 
butes  for  the  specified  window. 

Description 

XGetwindowAttributes  returns  the  XWindowAttributes  structure  containing  the  cur 
rent  window  attributes. 

While  w  is  defined  as  type  window,  a  Pixmap  can  also  be  used,  in  which  case  all  the  returned 
members  will  be  zero  except  width,  height,  depth,  and  screen. 

XGetwindowAttributes  returns  a  Status  of  zero  on  failure,  or  nonzero  on  success. 
However,  it  will  only  return  zero  if  you  have  defined  an  error  handler  that  does  not  exit,  using 
xSetErrorHandler.  The  default  error  handler  exits,  and  therefore  XGetwindow 
Attributes  never  gets  a  chance  to  return.  (This  is  relevant  only  if  you  are  writing  a  window 
manager  or  other  application  that  deals  with  windows  that  might  have  been  destroyed.) 

The  following  list  briefly  describes  each  member  of  the  XWindowAttributes  structure.  For 
more  information,  see  Volume  One,  Chapter  4,  Window  Attributes. 

x,  y  The  current  position  of  the  upper-left  pixel  of  the  window's  border,  relative 

to  the  origin  of  its  parent. 

width,  height  The  current  dimensions  in  pixels  of  this  window. 

border_width     The  current  border  width  of  the  window. 

depth  The  number  of  bits  per  pixel  in  this  window. 

visual  The  visual  structure. 

root  The  root  window  ID  of  the  screen  containing  the  window. 

class  The  window  class.  One  of  these  constants:    InputOutput  or  Input- 

Only. 

bit_gravity  The  new  position  for  existing  contents  after  resize.  One  of  the  constants 
ForgetGravity,  StaticGravity,  or  CenterGravity,  or  one  of 
the  compass  constants  (NorthWestGravity,  NorthGravity,  etc.). 


Xlib  Reference  Manual  26 1 


X  Get  Window  Attributes  (continued)  Xlib  -  Window  Attributes 

win_gravity  The  new  position  for  this  window  after  its  parent  is  resized.  One  of  the 
constants  CenterGravity,  UnmapGravity,  StaticGravity,  or 
one  of  the  compass  constants. 

backing_store  When  to  maintain  contents  of  the  window.  One  of  these  constants:  Not- 
Usef  ul,  WhenMapped,  or  Always. 

backing_jplanes 

The  bit  planes  to  be  preserved  in  a  backing  store. 

backing_jpixel  The  pixel  value  used  when  restoring  planes  from  a  partial  backing  store. 

save_under  A  boolean  value,  indicating  whether  saving  bits  under  this  window  would 
be  useful. 

colormap  The  colormap  ID  being  used  in  this  window,  or  None. 

map_installed  A  boolean  value,  indicating  whether  the  colormap  is  currently  installed.  If 
True,  the  window  is  being  displayed  in  its  chosen  colors. 

map_state  The  window's  map  state.   One  of  these  constants:    isUnmapped,  Is- 

Unviewable,  or  IsViewable.  IsUnviewable  indicates  that  the 
specified  window  is  mapped  but  some  ancestor  is  unmapped. 

a 1 l_e ve n t_ma  s  k  s 

The  set  of  events  any  client  have  selected.  This  member  is  the  bitwise 
inclusive  OR  of  all  event  masks  selected  on  the  window  by  all  clients. 

your_event_mask 

The  bitwise  inclusive  OR  of  all  event  mask  symbols  selected  by  the  query 
ing  client. 

do_not_propagate_mask 

The  bitwise  inclusive  OR  of  the  event  mask  symbols  that  specify  the  set  of 
events  that  should  not  propagate.  This  is  global  across  all  clients. 

override_redirect 

A  boolean  value,  indicating  whether  this  window  will  override  structure 
control  facilities.  This  is  usually  only  used  for  temporary  pop-up  windows 
such  as  menus.  Either  True  or  False. 

screen  A  pointer  to  the  Screen  structure  for  the  screen  containing  this  window. 

Errors 

BadWindow 

Structures 

The  xwindowAttributes  structure  contains: 

typedef  struct  { 

int  x,  y;  /*  location  of  window  */ 

int  width,  height;  /*  width  and  height  of  window  */ 

int  border_width;  /*  border  width  of  window  */ 

int  depth;  /*  depth  of  window  */ 
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Visual  *visual;  /* 

Window  root;  /* 

int  class;  /* 

int  bit_gravity;  /* 

int  win_gravity;  /* 

int  backing_store;  /* 
unsigned  long  backing_planes; /* 

unsigned  long  backing_pixel;  /* 

Bool  save_under;  /* 

Colormap  colormap;  /* 

Bool  map_installed;  /* 

int  map_state;  /* 

long  all_event_masks;  /* 

long  your_event_mask;  /* 

long  do_not_propagate_mask;  /* 

Bool  override_redirect;  /* 

Screen  *screen;  /* 
}  XWindowAttributes; 


the  associated  visual  structure  */ 
root  of  screen  containing  window  */ 
InputOutput,  InputOnly*/ 
one  of  bit  gravity  values  */ 
one  of  the  window  gravity  values  */ 
NotUseful,  WhenMapped,  Always  */ 
planes  to  be  preserved  if  possible  */ 
value  to  be  used  when  restoring  planes  */ 
boolean,  should  bits  under  be  saved  */ 
colormap  to  be  associated  with  window  */ 
boolean,  is  colormap  currently  installed*/ 
IsUnmapped,  IsUnviewable,  IsViewable  */ 
set  of  events  all  people  have  interest  in*/ 
my  event  mask  */ 

set  of  events  that  should  not  propagate  */ 
boolean  value  for  override-redirect  */ 
pointer  to  correct  screen  */ 


Related  Commands 

XChangeWindowAttributes,  XGetGeometry,  XSetWindowBackground,  XSet- 
WindowBackgroundPixmap,  XSetWindowBorder,  XSetWindowBorderPixmap. 
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XGetWindowProperty  \ X)|b  _  Propartl8s_ 

Name 

XGetWindowProperty  —  obtain  the  atom  type  and  property  format  for  a  window. 

Synopsis 

int    XGetWindowProperty ( display,    w,    property,    long_offset, 

long_length,    delete,    req_type,    actual_type,    actual_for- 
mat ,    nit  ems ,    bytes_after ,    prop) 
Display    *display; 
Window   w; 
Atom  property; 

long   long_offset ,    long_length; 
Bool   delete; 
Atom   req_type; 

Atom   *actual_type;  /*  RETURN    */ 

int    *actual_format;  /*  RETURN    */ 

unsigned   long    *nitems;  /*  RETURN    */ 

unsigned   long    *bytes_after;       /*  RETURN    */ 
unsigned  char   **prop;  /*  RETURN    */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  whose  atom  type  and  property  format  you 

want  to  obtain. 

property         Specifies  the  atom  of  the  desired  property. 

1  ong_offset  Specifies  the  offset  in  32-bit  quantities  where  data  will  be  retrieved. 

1  ong_length  Specifies  the  length  in  32-bit  multiples  of  the  data  to  be  retrieved. 

delete  Specifies  a  boolean  value  of  True  or  False.  If  you  pass  True  and  a  prop 

erty  is  returned,  the  property  is  deleted  from  the  window  after  being  read  and 
a  PropertyNotif  y  event  is  generated  on  the  window. 

req_type  Specifies  an  atom  describing  the  desired  format  of  the  data.  If  Any- 
Proper  tyType  is  specified,  returns  the  property  from  the  specified  window 
regardless  of  its  type.  If  a  type  is  specified,  the  function  returns  the  property 
only  if  its  type  equals  the  specified  type. 

actual_type  Returns  the  actual  type  of  the  property. 

actual_for/nat 

Returns  the  actual  data  type  of  the  returned  data. 

ni  terns  Returns  the  actual  number  of  8-,  16-,  or  32-bit  items  returned  in  prop. 

bytes_after  Returns  the  number  of  bytes  remaining  to  be  read  in  the  property  if  a  partial 
read  was  performed. 
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prop  Returns  a  pointer  to  the  data  actually  returned,  in  the  specified  format. 

XGetWindowProperty  always  allocates  one  extra  byte  after  the  data  and 
sets  it  to  NULL.  This  byte  is  not  counted  in  nit  ems. 

Description 

XGetWindowProperty  gets  the  value  of  a  property  if  it  is  the  desired  type.  XGetwindow- 
P  rope  rt y  sets  the  return  arguments  acccording  to  the  following  rules: 

If  the  specified  property  does  not  exist  for  the  specified  window,  then:  act  ual_ type  is 
None;  act ual_format  =  0;  and  bytes_af ter  =  0.  delete  is  ignored  in  this 
case,  and  nit  ems  is  empty. 

If  the  specified  property  exists,  but  its  type  does  not  match  req_type,  then: 
actual_type  is  the  actual  property  type;  actual_format  is  the  actual  property 
format  (never  zero);  and  bytes_after  is  the  property  length  in  bytes  (even  if 
actual_format  is  16  or  32).  delete  is  ignored  in  this  case,  and  ni  terns  is  empty. 

If  the  specified  property  exists,  and  either  recj_type  is  AnyPropertyType  or  the 
specified  type  matches  the  actual  property  type,  then:  actual_type  is  the  actual  prop 
erty  type;  and  actual_format  is  the  actual  property  format  (never  zero). 
jbytes_ar"ter  and  nit  ems  are  defined  by  combining  the  following  values: 

N   =  actual  length  of  stored  property  in  bytes  (even  if  act  ual_format  is  16  or  3  2) 
1   =   4*    1  on g_off set  (convert  offset  from  longs  into  bytes) 
L   =   MINIMUM* (N    -    I),    4    *    long_length)     (BadValue    if   L    <    0) 
bytes_after   =   N   -    (I    +   L)    (number  of  trailing  unread  bytes  in  stored  property) 

The  returned  data  (in  prop)  starts  at  byte  index  I  in  the  property  (indexing  from  0).  The 
actual  length  of  the  returned  data  in  bytes  is  L.  L  is  converted  into  the  number  of  8-,  16-, 
or  32-bit  items  returned  by  dividing  by  1, 2,  or  4  respectively  and  this  value  is  returned  in 
nitems.  The  number  of  trailing  unread  bytes  is  returned  in  by  t  es_aft  er. 

If  delete  ==  True  and  bytes_after  ==  0  the  function  deletes  the  property 
from  the  window  and  generates  a  PropertyNotif  y  event  on  the  window. 

When  XGetWindowProperty  executes  successfully,  it  returns  Success.  The  Success 
return  value  and  the  undocumented  value  returned  on  failure  are  the  opposite  of  all  other  rou 
tines  that  return  int  or  Status.  The  value  of  Success  is  undocumented,  but  is  zero  (0)  in 
the  current  sample  implementation  from  MIT.  The  failure  value,  also  undocumented,  is  cur 
rently  one  (1).  Therefore,  comparing  either  value  to  True  or  False,  or  using  the  syntax  "if 
( !  XGetWindowProperty  (  .  .  .  ))"  is  not  allowed. 

To  free  the  resulting  data,  use  XFree. 

For  more  information,  see  Volume  One,  Chapter  WJnterdient  Communication. 
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Errors 

BadAtom 

BadVa  lue          Value  of  I  ong_offset  caused  L  to  be  negative  above. 
BadWindow 

Related  Commands 

XChangeProperty, XGetAtomName, XGetFontProperty,  XListProperties, 
XRotateWindowProperties,XSetStandardProperties. 
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Name 

XGetWMHintS  —  read  the  window  manager  hints  property. 

Synopsis 

XWMHints  *XGetWMHints (display,  w) 
Display  *  display; 
Window  w; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  to  be  queried. 

Description 

This  function  is  primarily  for  window  managers.  XGetWMHintS  returns  NULL  if  no 
XA_WM_HINTS  property  was  set  on  window  w,  and  returns  a  pointer  to  an  XWMHints  structure 
if  it  succeeds.  Programs  must  free  the  space  used  for  that  structure  by  calling  XFree. 

For  more  information  on  using  hints,  see  Volume  One,  Chapter  10,  Inter -client  Communication. 
Structures 

typedef  struct  { 

long  flags;  /*  marks  which  fields  in  this  structure  are  defined  */ 

Bool  input;  /*  does  application  need  window  manager  for  input  */ 

int  initial_state;  /*  see  below  */ 

Pixmap  icon_pixmap;  /*  pixmap  to  be  used  as  icon  */ 

Window  icon_window;  /*  window  to  be  used  as  icon  */ 

int  icon  x,  icon  y;  /*  initial  position  of  icon  */ 

Pixmap  icon_mask;  /*  icon  mask  bitmap  */ 

XID  window  group;  /*  ID  of  related  window  group  */ 

/*  this  structure  may  be  extended  in  the  future  */ 
}  XWMHints; 

/*  initial  state  flag:  */ 

#define  DontCareState  0 

#define  NormalState  1 

#define  ZoomState  2 

#define  IconicState  3 

#define  InactiveState  4 

Errors 

BadWindow 

Related  Commands 

XAllocWMHints, XFetchName, XGetClassHint,  XGetlconName,  XGetlcon- 
Sizes,  XGetNormalHints, XGetSizeHints,  XGetTransientForHint, XGet- 
ZoomHints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, 
XSetNormalHints, XSetSizeHints, XSetTransientForHint,  XSetWMHints, 
XSetZoomHints, XStoreName, XSetWMProperties. 
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Name 

XGetZoomHints  —  read  the  size  hints  property  of  a  zoomed  window. 

Synopsis 

Status  XGetZoomHints (display,  w,  zhints) 
Display  *display; 
Window  w; 
XSizeHints  *zhints;        /*  RETURN  */ 

Arguments 

di  spl  ay        Specifies  a  connection  to  an  X  server;  returned  from  XOpenD  i  sp  1  ay . 

w  Specifies  the  ID  of  the  window  to  be  queried. 

zhints  Returns  a  pointer  to  the  zoom  hints. 

Description 

XGetZoomHints  is  obsolete  beginning  in  Release  4,  because  zoom  hints  are  no  longer 
defined  in  the  ICCCM. 

XGetZoomHints  is  primarily  for  window  managers.  XGetZoomHints  returns  the  size 
hints  for  a  window  in  its  zoomed  state  (not  normal  or  iconified)  read  from  the 
XA_WM_ZOOM_HINTS  property.  It  returns  a  nonzero  Status  if  it  succeeds,  and  zero  if  the 
application  did  not  specify  zoom  size  hints  for  this  window. 

For  more  information  on  using  hints,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Structures 

typedef  struct  { 

long  flags;     /*  which  fields  in  structure  are  defined  */ 

int  x,  y; 

int  width,  height; 

int  min_width,  min__height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x;      /*  numerator  */ 

int  y;      /*  denominator  */ 
}  min_aspect,  max_aspect; 
}  XSizeHints; 

/*  flags  argument  in  size  hints  */ 

tdefine  USPosition  (1L  «  0)  /*  user  specified  x,  y  */ 

#define  USSize      (1L  «  1)  /*  user  specified  width,  height  */ 

#define  PPosition  (1L  «  2)  /*  program  specified  position  */ 

tdefine  PSize  (1L  «  3)  /*  program  specified  size  */ 

tdefine  PMinSize  (1L  «  4)  /*  program  specified  minimum  size  */ 

#define  PMaxSize  (1L  «  5)  /*  program  specified  maximum  size  */ 

#define  PResizelnc  (1L  «  6)  /*  program  specified  resize  increments  */ 
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#define  PAspect     (1L  «  7)  /*  program  specified  min/max  aspect  ratios  */ 
#def ine  PAllHints  (PPosition I PSize I PMinSize | PMaxSize I PResizelnc I PAspect) 

Errors 

BadWindow 

Related  Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints,  XSetClass- 
Hint,  XSetCommand, XSetlconName, XSetlconSizes, XSetNormalHints, XSet- 
SizeHints,  XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore- 
Name. 
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XGrabButton  V 


Name 

XGrabButton  —  grab  a  pointer  button. 

Synopsis 

XGrabButton ( display,  button,  modifiers,  grab_window, 

owner_events ,  event_mask,  pointer_mode,  keyboard_mode , 
confine_to,  cursor) 

Display  *display; 

unsigned  int  button; 

unsigned  int  modifiers; 

Window  grab_window; 

Bool  owner_events ; 

unsigned  int  event_mask; 

int  point er_mode ,  keyboard_mode ; 

Window   confine_to; 

Cursor  cursor; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

button  Specifies  the  mouse  button.  May  be  Buttonl,  Button2,  Buttons,  But- 

ton4,  Buttons,  or  AnyButton.  The  constant  AnyButton  is  equivalent 
to  issuing  the  grab  request  for  all  possible  buttons.  The  button  symbols  can 
not  be  ORed. 

modifiers  Specifies  a  set  of  keymasks.  This  is  a  bitwise  OR  of  one  or  more  of  the  fol 
lowing  symbols:  ShiftMask,  LockMask,  ControlMask,  ModlMask, 
Mod2Mask,  ModSMask,  Mod4Mask,  ModSMask,  or  AnyModifier. 
AnyModif  ier  is  equivalent  to  issuing  the  grab  key  request  for  all  possible 
modifier  combinations  (including  no  modifiers). 

grab_window  Specifies  the  ID  of  the  window  you  want  to  the  grab  to  occur  in. 

owner_e vents 

Specifies  a  boolean  value  of  either  True  or  False.  See  Description  below. 

event_mask  Specifies  the  event  mask  to  take  effect  during  the  grab.  This  mask  is  the  bit 
wise  OR  of  one  or  more  of  the  event  masks  listed  on  the  reference  page  for 
XSelectlnput. 

point er_mode 

Controls  processing  of  pointer  events  during  the  grab.  Pass  one  of  these  con 
stants:  GrabModeSync  or  GrabModeAsync. 

keyboa rd_mode 

Controls  processing  of  keyboard  events  during  the  grab.  Pass  one  of  these 
constants:  GrabModeSync  or  GrabModeAsync. 

confine_to  Specifies  the  ID  of  the  window  to  confine  the  pointer.  One  possible  value  is 
the  constant  None,  in  which  case  the  pointer  is  not  confined  to  any  window. 
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cursor  Specifies  the  cursor  to  be  displayed  during  the  grab.  One  possible  value  you 

can  pass  is  the  constant  None,  in  which  case  the  existing  cursor  is  used. 

Description 

XGrabButton  establishes  a  passive  grab,  such  that  an  active  grab  may  take  place  when  the 
specified  key/button  combination  is  pressed  in  the  specified  window.  After  this  call,  if 

1)  the  specified  button  is  pressed  when  the  specified  modifier  keys  are  down  (and  no  other 
buttons  or  modifier  keys  are  down), 

2)  grab_window  contains  the  pointer, 

3)  the  conf±ne_to  window  (if  any)  is  viewable,  and 

4)  these  constraints  are  not  satisfied  for  any  ancestor, 

then  the  pointer  is  actively  grabbed  as  described  in  XGrabPointer,  the  last  pointer  grab  time 
is  set  to  the  time  at  which  the  button  was  pressed,  and  the  ButtonPress  event  is  reported. 

The  interpretation  of  the  remaining  arguments  is  as  for  XGrabPointer.  The  active  grab  is 
terminated  automatically  when  all  buttons  are  released  (independent  of  the  state  of  modifier 
keys). 

A  modifier  of  AnyModif  ier  is  equivalent  to  issuing  the  grab  request  for  all  possible  modifier 
combinations  (including  no  modifiers).  A  button  of  AnyButton  is  equivalent  to  issuing  the 
request  for  all  possible  buttons  (but  at  least  one). 

XGrabButton  overrides  all  previous  passive  grabs  by  the  same  client  on  the  same  key/button 
combination  on  the  same  window,  but  has  no  effect  on  an  active  grab.  The  request  fails  if  some 
other  client  has  already  issued  an  XGrabButton  with  the  same  button/key  combination  on  the 
same  window.  When  using  AnyModif  ier  or  AnyButton,  the  request  fails  completely  (no 
grabs  are  established)  if  there  is  a  conflicting  grab  for  any  combination. 

The  owner_e vents  argument  specifies  whether  the  grab  window  should  receive  all  events 
(False)  or  whether  the  grabbing  application  should  receive  all  events  normally  (True). 

The  pointer_mode  and  keyboard_mode  control  the  processing  of  events  during  the  grab. 
If  either  is  GrabModeSync,  events  for  that  device  are  not  sent  from  the  server  to  Xlib  until 
XAllowEvent  s  is  called  to  release  the  events.  If  either  is  GrabModeAsync,  events  for  that 
device  are  sent  normally. 

An  automatic  grab  takes  place  between  a  ButtonPress  event  and  the  corresponding 
ButtonRelease  event,  so  this  call  is  not  necessary  in  some  of  the  most  common  situations. 
But  this  call  is  necessary  for  certain  styles  of  menus. 

For  more  information  on  grabbing,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
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Errors 

BadAccess        When  using  AnyModif  ier  or  AnyButton  and  there  is  a  conflicting  grab 
by  another  client.  No  grabs  are  established. 

Another  client  has  already  issued  an  XGrabButton  request  with  the  same 
key/button  combination  on  the  same  window. 

BadCursor 

BadValue 

BadWindow 

Related  Commands 

XChangeActivePointerGrab,  XGrabKey,  XGrabKeyboard,  XGrabPointer, 
XGrabServer, XUngrabButton, XUngrabKey,  XUngrabKeyboard, XUngrab- 
Pointer,  XUngrabServer. 
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Name 

XGrabKey  —  grab  a  key. 

Synopsis 

XGrabKey (display,  keycode,  modifiers,  grab_window , 
owner_events,  pointer_mode ,  keyboard_mode) 
Display  *display; 
int  keycode ; 
unsigned  int  modifiers; 
Window  grab_window; 
Bool  owner_events ; 
int  pointer_mode ,  keyboard_mode ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

keycode  Specifies  the  keycode  to  be  grabbed.  It  may  be  a  modifier  key.  Specifying 

AnyKey  is  equivalent  to  issuing  the  request  for  all  key  codes. 

modifiers  Specifies  a  set  of  keymasks.  This  is  a  bitwise  OR  of  one  or  more  of  the  fol 
lowing  symbols:  ShiftMask,  LockMask,  ControlMask,  ModlMask, 
Mod2Mask,  Mod3Mask,  Mod4Mask,  ModSMask,  or  AnyModifier. 
AnyModif  ier  is  equivalent  to  issuing  the  grab  key  request  for  all  possible 
modifier  combinations  (including  no  modifiers).  All  specified  modifiers  do 
not  need  to  have  currently  assigned  keycodes. 

gr  a  £>_  window  Specifies  the  window  in  which  the  specified  key  combination  will  initiate  an 
active  grab. 

owner_events 

Specifies  whether  the  grab  window  should  receive  all  events  (True)  or 
whether  the  grabbing  application  should  receive  all  events  normally 
(False). 

point  er_mode 

Controls  processing  of  pointer  events  during  the  grab.  Pass  one  of  these  con 
stants:  GrabModeSync  or  GrabModeAsync. 

keyboa rd_mode 

Controls  processing  of  keyboard  events  during  the  grab.  Pass  one  of  these 
constants:  GrabModeSync  or  GrabModeAsync. 

Description 

XGrabKey  establishes  a  passive  grab  on  the  specified  keys,  such  that  when  the  specified 
key/modifier  combination  is  pressed,  the  keyboard  may  be  grabbed,  and  all  keyboard  events 
sent  to  this  application.  More  formally,  once  an  XGrabKey  call  has  been  issued  on  a  particular 
key /button  combination: 
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•  IF  the  keyboard  is  not  already  actively  grabbed, 

•  AND  the  specified  key,  which  itself  can  be  a  modifier  key,  is  logically  pressed  when  the 
specified  modifier  keys  are  logically  down, 

AND  no  other  keys  or  modifier  keys  are  logically  down, 

AND  EITHER  the  grab  window  is  an  ancestor  of  (or  is)  the  focus  window  OR  the  grab 
window  is  a  descendent  of  the  focus  window  and  contains  the  pointer, 

•  AND  a  passive  grab  on  the  same  key  combination  does  not  exist  on  any  ancestor  of  the 
grab  window, 

THEN  the  keyboard  is  actively  grabbed,  as  for  XGrabKeyboard,  the  last  keyboard  grab 
time  is  set  to  the  time  at  which  the  key  was  pressed  (as  transmitted  in  the  KeyPress 
event),  and  the  KeyPress  event  is  reported. 

The  active  grab  is  terminated  automatically  when  the  specified  key  is  released  (independent  of 
the  state  of  the  modifier  keys). 

The  pointer_mode  and  keyboard_mode  control  the  processing  of  events  during  the  grab. 
If  either  is  GrabModeSync,  events  for  that  device  are  not  sent  from  the  server  to  Xlib  until 
XAllowEvents  is  called  to  send  the  events.  If  either  is  GrabModeAsync,  events  for  that 
device  are  sent  normally. 

For  more  information  on  grabbing,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 

Errors 

BadAccess        When  using  AnyModif  ier  or  AnyKey  and  another  client  has  grabbed  any 
overlapping  combinations.  In  this  case,  no  grabs  are  established. 

Another  client  has  issued  XGrabKey  for  the  same  key  combination  in 

grab_window. 

BadValue          key  code  is  not  in  the  range  between  min_keycode  and  max_keycode 
as  returned  by  XDisplayKeycodes. 

BadWindow 

Related  Commands 

XChangeActivePointerGrab,  XGrabButton,  XGrabKeyboard,  XGrabPointer, 
XGrabServer, XUngrabButton, XUngrabKey,  XUngrabKeyboard, XUngrab- 
Pointer, XUngrabServer. 
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—  Xlib -Grabbing- 


J  XGrabKeyboard 


Name 

XGrabKeyboard  —  grab  the  keyboard. 

Synopsis 

int  XGrabKeyboard (display,  grab_window,  owner_events, 

point er_mode,  keyboard_mode,  time) 
Display  *display; 
Window  grab_window; 
Bool  o wner_e vents; 
int  pointer_mode,  keyboard_mode ; 
Time  time; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

grab_window  Specifies  the  ID  of  the  window  that  requires  continuous  keyboard  input. 

owner_e vents 

Specifies  a  boolean  value  of  either  True  or  False.  See  Description  below. 

point  er_mode 

Controls  processing  of  pointer  events  during  the  grab.   Pass  either  Grab- 
ModeSync  or  GrabModeAsync. 

k eyb oard_mode 

Controls  processing  of  keyboard  events  during  the  grab.  Pass  either  Grab- 
ModeSync  or  GrabModeAsync. 

time  Specifies  the  time  when  the  grab  should  take  place.  Pass  either  a  timestamp, 

expressed  in  milliseconds,  or  the  constant  Cur  rent  Time. 

Description 

XGrabKeyboard  actively  grabs  control  of  the  main  keyboard.    Further  key  events  are 
reported  only  to  the  grabbing  client.  This  request  generates  Focus  In  and  FocusOut  events. 

XGrabKeyboard  processing  is  controlled  by  the  value  in  the  cw/jer_ events  argument: 
If  owner_events  is  False,  all  generated  key  events  are  reported  to  grab_window. 

If  owner_events  is  True,  then  if  a  generated  key  event  would  normally  be  reported 
to  this  client,  it  is  reported  normally.  Otherwise  the  event  is  reported  to  grab_window. 

Both  KeyPress  and  KeyRelease  events  are  always  reported,  independent  of  any 
event  selection  made  by  the  client. 

XGrabKeyboard  processing  of  pointer  events  and  keyboard  events  are  controlled  by 
poir7ter_modeand  A:eyboard_/node: 

•         If  the  pointer_mode  or  keyboard_mode  is  GrabModeAsync,  event  processing 
for  the  respective  device  continues  normally. 

For  keyboard_mode  GrabModeAsync  only:   if  the  keyboard  was  currently  frozen 
by  this  client,  then  processing  of  keyboard  events  is  resumed. 
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If  the  po±nter_mode  or  keyboard_mode  is  GrabModeSync,  events  for  the 
respective  device  are  queued  by  the  server  until  a  releasing  XAllowE vents  request 
occurs  or  until  the  keyboard  grab  is  released  as  described  above. 

If  the  grab  is  successful,  XGrabKeyboard  returns  the  constant  GrabSuccess.  XGrab 
Keyboard  fails  under  the  following  conditions  and  returns  the  following: 

If  the  keyboard  is  actively  grabbed  by  some  other  client,  it  returns  AlreadyGrabbed. 
•         If  grab_window  is  not  viewable,  it  returns  GrabNotViewable. 

If  time  is  earlier  than  the  last  keyboard  grab  time  or  later  than  the  current  server  time,  it 
returns  GrablnvalidTime. 

If  the  pointer  is  frozen  by  an  active  grab  of  another  client,  the  request  fails  with  a  status 
GrabFrozen. 

If  the  grab  succeeds,  the  last  keyboard  grab  time  is  set  to  the  specified  time,  with  Current- 
Time  replaced  by  the  current  X  server  time. 

For  more  information  on  grabbing,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 

Errors 

BadValue 
Badwindow 

Related  Commands 

XChangeActivePointerGrab,  XGrabButton,  XGrabKey,  XGrabPointer,  XGrab- 
Server,  XUngrabButton, XUngrabKey, XUngrabKeyboard,  XUngrabPointer, 
XUngrabServer. 
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Name 

XGrabPointer  —  grab  the  pointer. 

Synopsis 

int  XGrabPointer  (display,  grab_window,  owner_e vents, 

event_maskr  pointer_mode ,  keyboard_mode ,  confine_to, 
cursor,  time) 
Display  *display; 
Window  grab_window; 
Bool  owner_events ; 
unsigned  int  event_mask; 
int  point er_mode,  keyboard_mode; 
Window  confine_to; 
Cursor  cursor; 
Time  time; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

grab_window  Specifies  the  ID  of  the  window  that  should  grab  the  pointer  input  independent 
of  pointer  location. 

owner_e vents 

Specifies  if  the  pointer  events  are  to  be  reported  normally  within  this  applica 
tion  (pass  True)  or  only  to  the  grab  window  (pass  False). 

event_mask  Specifies  the  event  mask  symbols  that  can  be  ORed  together.  Only  events 
selected  by  this  mask,  plus  ButtonPress  and  ButtonRelease,  will  be 
delivered  during  the  grab.  See  XSelect  Input  for  a  complete  list  of  event 
masks. 

point  er_mode 

Controls  further  processing  of  pointer  events.  Pass  either  GrabModeSync 

or  GrabModeAsync. 

k eyb o a rd_m ode 

Controls  further  processing  of  keyboard  events.  Pass  either  GrabModeSync 
or  GrabModeAsync. 

confine_to  Specifies  the  ID  of  the  window  to  confine  the  pointer.  One  option  is  None,  in 
which  case  the  pointer  is  not  confined  to  any  window. 

cursor  Specifies  the  ID  of  the  cursor  that  is  displayed  with  the  pointer  during  the 

grab.  One  option  is  None,  which  causes  the  cursor  to  keep  its  current  pattern. 

time  Specifies  the  time  when  the  grab  request  took  place.  Pass  either  a  timestamp, 

expressed  in  milliseconds  (from  an  event),  or  the  constant  Cur  rent  Time. 
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Description 

XGrabPointer  actively  grabs  control  of  the  pointer.  Further  pointer  events  are  only  reported 
to  the  grabbing  client  until  XUngrabPo inter  is  called. 

event_mask  is  always  augmented  to  include  ButtonPressMask  and  ButtonRelease- 
Mask.  If  owner_events  is  False,  all  generated  pointer  events  are  reported  to 
grab_window,  and  are  only  reported  if  selected  by  event_mask.  If  owner_e vents  is 
True,  then  if  a  generated  pointer  event  would  normally  be  reported  to  this  client,  it  is  reported 
normally;  otherwise  the  event  is  reported  with  respect  to  the  grrab_window,  and  is  only 
reported  if  selected  by  event_mask.  For  either  value  of  owner_e vents,  unreported  events 
are  discarded. 

point  er_mode  controls  processing  of  pointer  events  during  the  grab,  and  keyboard_mode 
controls  further  processing  of  main  keyboard  events.  If  the  mode  is  GrabModeAsync,  event 
processing  continues  normally.  If  the  mode  is  GrabModeSync,  events  for  the  device  are 
queued  by  the  server  but  not  sent  to  clients  until  the  grabbing  client  issues  a  releasing 
XAllowE  vents  request  or  an  XUngrabPo  inter  request. 

If  a  cursor  is  specified,  then  it  is  displayed  regardless  of  which  window  the  pointer  is  in.  If  no 
cursor  is  specified,  then  when  the  pointer  is  in  gra£>_window  or  one  of  its  subwindows,  the 
normal  cursor  for  that  window  is  displayed.  When  the  pointer  is  outside  grab_window,  the 
cursor  for  grab_ window  is  displayed. 

If  a  con  fin  e_  to  window  is  specified,  then  the  pointer  will  be  restricted  to  that  window.  The 
confine_to  window  need  have  no  relationship  to  the  graJb_window.  If  the  pointer  is  not 
initially  in  the  confine_to  window,  then  it  is  warped  automatically  to  the  closest  edge  (and 
enter/leave  events  generated  normally)  just  before  the  grab  activates.  If  the  conf~ine_to 
window  is  subsequently  reconfigured,  the  pointer  will  be  warped  automatically  as  necessary  to 
keep  it  contained  in  the  window. 

The  time  argument  lets  you  avoid  certain  circumstances  that  come  up  if  applications  take  a 
long  while  to  respond  or  if  there  are  long  network  delays.  Consider  a  situation  where  you  have 
two  applications,  both  of  which  normally  grab  the  pointer  when  clicked  on.  If  both  applica 
tions  specify  the  timestamp  from  the  ButtonPress  event,  the  second  application  will  suc 
cessfully  grab  the  pointer,  while  the  first  will  get  a  return  value  of  AlreadyGrabbed,  indicat 
ing  that  the  other  application  grabbed  the  pointer  before  its  request  was  processed.  This  is  the 
desired  response  because  the  latest  user  action  is  most  important  in  this  case. 

XGrabPointer  generates  EnterNotif  y  and  LeaveNotif  y  events. 

If  the  grab  is  successful,  it  returns  the  constant  GrabSuccess.  The  XGrabPointer  func 
tion  fails  under  the  following  conditions,  with  the  following  return  values: 

•         If  grab_window  or  conf~ine_to  window  is  not  viewable,  or  if  the  conf  ine_to 
window  is  completely  off  the  screen,  GrabNotviewable  is  returned. 

If  the  pointer  is  actively  grabbed  by  some  other  client,  the  constant  AlreadyGrabbed 
is  returned. 

If  the  pointer  is  frozen  by  an  active  grab  of  another  client,  GrabFrozen  is  returned. 


278  Xlib  Reference  Manual 


Xllb  -  Grabbing  (continued)  XGrabPointer 

If  the  specified  time  is  earlier  than  the  last-pointer-grab  time  or  later  than  the  current  X 
server  time,  GrablnvalidTime  is  returned.  (If  the  call  succeeds,  the  last  pointer  grab 
time  is  set  to  the  specified  time,  with  the  constant  CurrentTime  replaced  by  the  cur 
rent  X  server  time.) 

For  more  information  on  grabbing,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 

Errors 

BadCursor 

BadValue 

BadWindow 

Related  Commands 

XChangeActivePointerGrab,  XGrabButton,  XGrabKey,  XGrabKeyboard, 
XGrabServer, XUngrabButton, XUngrabKey,  XUngrabKeyboard, XUngrab- 
Pointer, XUngrabServer. 
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XGrabServer 

Xllb  -  Grabbing  — 

Name 

XGrabServer  —  grab  the  server. 

Synopsis 

XGrabServer  (display) 
Display  * display ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

Description 

Grabbing  the  server  means  that  only  requests  by  the  calling  client  will  be  acted  on.  All  others 
will  be  queued  in  the  server  until  the  next  XUngrabServer  call.  The  X  server  should  not  be 
grabbed  any  more  than  is  absolutely  necessary. 

Related  Commands 

XChangeActivePointerGrab,  XGrabButton,  XGrabKey,  XGrabKeyboard, 
XGrabPointer, XUngrabButton, XUngrabKey, XUngrabKeyboard, XUngrab- 
Pointer,  XUngrabServer. 
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Name 

XlconifyWindow  —  request  that  a  top-level  window  be  iconified. 

Synopsis 

Status  XlconifyWindow (display,  w,  screen_number) 
Display  * display; 
Window  w; 
int  screen_n umber; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

w  Specifies  the  window. 

s c r e en_n umbe r 

Specifies  the  appropriate  screen  number  on  the  server. 

Availability 

Release  4  and  later. 

Description 

XlconifyWindow  sends  a  WM_CHANGE_STATE  ClientMessage  event  with  a  format  of  32 
and  a  first  data  element  of  Iconics t ate  (as  described  in  Section  4.1.4  of  the  Inter-Client 
Communication  Conventions  Manual  in  Volume  Zero,  X  Protocol  Reference  Manual),  to  the 
root  window  of  the  specified  screen.  Window  managers  may  elect  to  receive  this  message  and, 
if  the  window  is  in  its  normal  state,  may  treat  it  as  a  request  to  change  the  window's  state  from 
normal  to  iconic.  If  the  WM_CHANGE_STATE  property  cannot  be  interned,  XlconifyWindow 
does  not  send  a  message  and  returns  a  zero  status.  It  returns  a  nonzero  status  if  the  client  mes 
sage  is  sent  successfully;  otherwise,  it  returns  a  zero  status. 

For  more  information,  see  Volume  One,  Chapter  WJnterclient  Communication. 

Errors 

BadWindow 

Related  Commands 

XReconfigureWindow, XWithdrawWindow. 
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Xlf  EVent  V xilb  -  input  Hand.ing- 

Name 

XlfEvent  —  wait  for  event  matched  in  predicate  procedure. 

Synopsis 

XlfEvent ( display ,  event,  predicate,  args) 
Display  *d±splay; 

XEvent  *  event;  /*  RETURN  */ 

Bool  (*predicate)  ()  ; 
char  *args; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

event  Returns  the  matched  event. 

predicate       Specifies  the  procedure  to  be  called  to  determine  if  the  next  event  satisfies 
your  criteria. 

args  Specifies  the  user- specified  arguments  to  be  passed  to  the  predicate  proce 

dure. 

Description 

XlfEvent  checks  the  event  queue  for  events,  uses  the  user-supplied  routine  to  check  if  one 
meets  certain  criteria,  and  removes  the  matching  event  from  the  input  queue.  XlfEvent 
returns  only  when  the  specified  predicate  procedure  returns  True  for  an  event.  The  specified 
predicate  is  called  once  for  each  event  on  the  queue  until  a  match  is  made,  and  each  time  an 
event  is  added  to  the  queue,  with  the  arguments  display,  event,  and  arg. 

If  no  matching  events  exist  on  the  queue,  XlfEvent  flushes  the  request  buffer  and  waits  for  an 
appropriate  event  to  arrive.  Use  XChecklf Event  if  you  don't  want  to  wait  for  an  event. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event,  XCheckTypedWindowEvent, XCheckWindowEvent,  XEvent sQueued, 
XGetlnputFocus,  XGetMotionEvents, XMaskEvent, XNextEvent, XPeekEvent, 
XPeeklf Event, XPending, XPutBackEvent,  XSelectlnput,  XSendEvent,  XSet- 
InputFocus, XSynchronize, XWindowEvent. 
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— Xlib  -  Resource  Manager- 


J  XlnsertModifiermapEntry 


Name 

XlnsertModifiermapEntry  —  add  a  new  entry  to  an  XModif  ierKeymap  structure. 
Synopsis 

XModif  ierKeymap  *XInsertModif  iermapEntry  (modmap, 

keysym_entry,  modifier) 
XModif ierKeymap  * modmap; 
KeyCode  keysym_entry ; 
int  modifier; 

Arguments 

modmap  Specifies  a  pointer  to  an  XModif  ierKeymap  structure. 

£  ey  sym_  entry 

Specifies  the  keycode  of  the  key  to  be  added  to  modmap. 

modifier  Specifies  the  modifier  you  want  mapped  to  the  keycode  specified  in 
keysym_entry.  This  should  be  one  of  the  constants:  Shif  tMaplndex, 
LockMapIndex,  ControlMapIndex,  ModlMapIndex,  Mod2Map- 
Index,  ModSMapIndex,  Mod4MapIndex,  or  ModSMapIndex. 

Description 

XlnsertModifiermapEntry  returns  an  XModif  ierKeymap  structure  suitable  for  cal 
ling  xsetModif  ierMapping,  in  which  the  specified  keycode  is  deleted  from  the  set  of  key- 
codes  that  is  mapped  to  the  specified  modifier  (like  Shift  or  Control).  Xlnsert 
ModifiermapEntry  does  not  change  the  mapping  itself. 

This  function  is  normally  used  by  calling  XGetModif  ierMapping  to  get  a  pointer  to  the 

current  XModif  ierKeymap  structure  for  use  as  the  modmap  argument  to  Xlnsert- 

Modi  f  ie  rmapEnt  r y . 

Note  that  the  structure  pointed  to  by  modmap  is  freed  by  XlnsertModifiermapEntry.  It 

should  not  be  freed  or  otherwise  used  by  applications. 

For  a  description  of  the  modifier  map,  see  XSetModif  ierMapping. 

Structures 

typedef  struct  { 

int  max_keypermod;     /*  server's  max  number  of  keys  per  modifier  */ 
KeyCode  *modif iermap;  /*  an  8  by  max_keypermod  array  of 

*  keycodes  to  be  used  as  modifiers  */ 

}  XModif ierKeymap; 

#define  ShiftMapIndex  0 

#define  LockMapIndex  1 

#define  ControlMapIndex  2 
#define  ModlMapIndex 

#define  Mod2MapIndex  4 

#define  ModSMapIndex  5 
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fdefine   Mod4MapIndex  6 

tdefine   ModSMapIndex  7 

Related  Commands 

XDeleteModif iermapEntry, XFreeModif iermap,  XGetKeyboardMapping, 
XGetModif  ierMapping,  XKeycodeToKeysym,  XKeysymToKeycode,  XKeysymTo- 
String,  XLookupKeysym,  XLookupString,  XNewModif ierMap,  XQueryKeymap, 
XRebindKeySym,  XRef reshKeyboardMapping,  XSetModif ierMapping, 
XStringToKeysym. 
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— Xlib- Colormaps- 


j  XlnstallColormap 


Name 

XlnstallColormap  —  install  a  colormap. 

Synopsis 

XlnstallColormap  ( display,    cmap) 
Display    * display; 
Colormap    cmap; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

cmap  Specifies  the  colormap  to  install. 

Description 

XlnstallColormap  installs  a  virtual  colormap  into  a  hardware  company.  If  there  is  only 
one  hardware  colormap,  XlnstallColormap  loads  a  virtual  colormap  into  the  hardware 
colormap.  All  windows  associated  with  this  colormap  immediately  display  with  their  chosen 
colors.  Other  windows  associated  with  the  old  colormap  will  display  with  false  colors. 

If  additional  hardware  colormaps  are  possible,  XlnstallColormap  loads  the  new  hardware 
map  and  keeps  the  existing  ones.  Other  windows  will  then  remain  in  their  true  colors  unless  the 
limit  for  colormaps  has  been  reached.  If  the  maximum  number  of  allowed  hardware  colormaps 
is  already  installed,  an  old  colormap  is  swapped  out  The  MinCmapsOf  Screen  (screen) 
and  MaxCmapsOf  Screen  (screen)  macros  can  be  used  to  determine  how  many  hardware 
colormaps  are  supported. 

If  cmap  is  not  already  an  installed  map,  a  ColormapNotify  event  is  generated  on  every 
window  having  cmap  as  an  attribute.  If  a  colormap  is  uninstalled  as  a  result  of  the  install,  a 
ColormapNotify  event  is  generated  on  every  window  having  that  colormap  as  an  attribute. 

Colormaps  are  usually  installed  and  uninstalled  by  the  window  manager,  not  by  clients. 

At  any  time,  there  is  a  subset  of  the  installed  colormaps,  viewed  as  an  ordered  list,  called  the 
"required  list."  The  length  of  the  required  list  is  at  most  the  min_maps  specified  for  each 
screen  in  the  Display  structure.  When  a  colormap  is  installed  with  XlnstallColormap  it 
is  added  to  the  head  of  the  required  list  and  the  last  colormap  in  the  list  is  removed  if  necessary 
to  keep  the  length  of  the  list  at  mim_maps.  When  a  colormap  is  uninstalled  with 
XUninstallColormap  and  it  is  in  the  required  list,  it  is  removed  from  the  list.  No  other 
actions  by  the  server  or  the  client  change  the  required  list.  It  is  important  to  realize  that  on  all 
but  high-performance  workstations,  min_maps  is  likely  to  be  1. 

If  the  hardware  colormap  is  immutable,  and  therefore  installing  any  colormap  is  impossible, 
XlnstallColormap  will  work  but  not  do  anything. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 
Errors 

BadColormap 
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Related  Commands 

Def aultColormap, DisplayCells,  XCopyColormapAndFree,  XCreate- 
Colormap, XFreeColormap, XGetStandardColormap, XListlnstalled- 
Colormaps,  XSetStandardColormap, XSetWindowColormap, XUninstall- 
Colormap. 
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-Xllb  -  Properties /  XlntelTlAtOm 

Name 

XInternAtom  —  return  an  atom  for  a  given  property  name  string. 

Synopsis 

Atom  XInternAtom  (display,  property_name,  only_if_exists) 
Display  *  display; 
char  *property_name ; 
Bool  only_if_exists ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

property_name 

Specifies  the  string  name  of  the  property  for  which  you  want  the  atom.  Upper 
or  lower  case  is  important.  The  string  should  be  in  ISO  LATIN- 1  encoding, 
which  means  that  the  first  128  character  codes  are  ASCII,  and  the  second  128 
character  codes  are  for  special  characters  needed  in  western  languages  other 
than  English. 

only_if_exists 

Specifies  a  boolean  value:  if  no  such  property_name  exists  Xlntern- 
Atom  will  return  None  if  this  argument  is  set  to  True  or  will  create  the  atom 
if  it  is  set  to  False. 

Description 

XInternAtom  returns  the  atom  identifier  corresponding  to  string  proper ty_name. 

If  the  atom  does  not  exist,  then  XInternAtom  either  returns  None  (if  only_if_exists  is 
True)  or  creates  the  atom  and  returns  its  ID  (if  only_if_exists  is  False). 

The  string  name  should  be  a  null-terminated.  Case  matters:  the  strings  "thing,"  "Thing,"  and 
"thinG"  all  designate  different  atoms. 

The  atom  will  remain  defined  even  after  the  client  that  defined  it  has  exited.  It  will  become 
undefined  only  when  the  last  connection  to  the  X  server  closes.  Therefore,  the  number  of  atoms 
interned  should  be  kept  to  a  minimum. 

This  function  is  the  opposite  of  XGetAtomName,  which  returns  the  atom  name  when  given  an 
atom  ID. 

Predefined  atoms  require  no  call  to  XInternAtom.  Predefined  atoms  are  defined  in 
<Xll/Xatom.h>  and  begin  with  the  prefix  "XA_".  Predefined  atoms  are  the  only  ones  that  do 
not  require  a  call  to  XInternAtom. 

Errors 

BadAlloc 
BadValue 
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Xlntern Atom  (continued)  Xlib  -  Properties 

Related  Commands 

XChangeProperty, XDeleteProperty, XGetAtomName,  XGetFontProperty, 
XGetWindowProperty, XListProperties,  XRotateWindowProperties, XSet- 
StandardProperties. 
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—  Xlib -Regions- 


/  XlntersectRegion 


Name 

XlntersectRegion  —  compute  the  intersection  of  two  regions. 
Synopsis 

XlntersectRegion (sra,    srb,    dr) 
Region    sra,    srb; 
Region   dr;  /*  RETURN    */ 

Arguments 

sra  Specify  the  two  regions  with  which  to  perform  the  computation. 

srb 

dr  Returns  the  result  of  the  computation. 

Description 

XlntersectRegion  generates  a  region  that  is  the  intersection  of  two  regions. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XOf f setRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, XSet- 
Region,  XShrinkRegion, XSubtractRegion,  XUnionRectWithRegion, XUnion- 
Region, XXorRegion. 
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XKeycodeToKeysym  \ X||b  Keyboard_ 

Name 

XKeycodeToKeysym  —  convert  a  key  code  to  a  keysym. 

Synopsis 

KeySym  XKeycodeToKeysym ( display,  keycode,  index) 
Display  *display; 
KeyCode  keycode ; 
int  index; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  xopenD  i  sp  1  ay . 

keycode  Specifies  the  keycode. 

index  Specifies  which  keysym  in  the  list  for  the  keycode  to  return. 

Description 

XKeycodeToKeysym  returns  one  of  the  keysyms  defined  for  the  specified  keycode. 
XKeycodeToKeysym  uses  internal  Xlib  tables,  index  specifies  which  keysym  in  the  array 
of  keysyms  corresponding  to  a  keycode  should  be  returned.  If  no  symbol  is  defined, 
XKeycodeToKeysym  returns  NoSymbol. 

Related  Commands 

IsCursorKey, IsFunctionKey,  IsKeypadKey,  IsMiscFunctionKey,  Is- 
Modif  ierKey,  IsPFKey,  XChangeKeyboardMapping,  XDeleteModif iermap- 
Entry, XDisplayKeycodes, XFreeModif iermap,  XGetKeyboardMapping, XGet- 
Modif ierMapping,  XInsertModif iermapEntry, XKeysymToKeycode,  XKeysym- 
ToString,  XLookupKeysym,  XLookupString,  XNewModif ierMap, XQuery- 
Keymap, XRebindKeySym,  XRef reshKeyboardMapping, XSetModif ierMapping, 
XStringToKeysym. 
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—  Xlib -Keyboard- 


J  XKeysymToKeycode 


Name 

XKeysymToKeycode  —  convert  a  keysym  to  the  appropriate  keycode. 

Synopsis 

KeyCode  XKeysymToKeycode (display,  keysym) 
Display  *display; 
Keysym  keysym; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

keysym  Specifies  the  keysym  that  is  to  be  searched  for. 

Description 

XKeysymToKeycode  returns  the  keycode  corresponding  to  the  specified  keysym  in  the  cur 
rent  mapping.  If  the  specified  keysym  is  not  defined  for  any  keycode,  XKeysymToKeycode 
returns  zero. 

Related  Commands 

IsCursorKey, IsFunctionKey, IsKeypadKey,  IsMiscFunctionKey, Is- 
Modif ierKey, IsPFKey,  XChangeKeyboardMapping,  XDeleteModif iermap- 
Entry,  XDisplayKeycodes, XFreeModif iermap,  XGetKeyboardMapping,  XGet- 
Modif ierMapping, XInsertModif iermapEntry, XKeycodeToKeysym,  XKeysym- 
ToString,  XLookupKeysym,  XLookupString,  XNewModif ierMap, XQuery- 
Keymap,  XRebindKeySym,  XRef reshKeyboardMapping,  XSetModif ierMapping, 
XSt r ingToKeysym. 
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XKeysymToString  \ XB>  _  Keyboard_ 

Name 

XKeysymToString  —  convert  a  keysym  symbol  to  a  string. 

Synopsis 

char  *XKeysymToSt ring (keysym) 
KeySym  keysym; 

Arguments 

keysym  Specifies  the  keysym  that  is  to  be  converted. 

Description 

XKeysymToString  converts  a  keysym  symbol  (a  number)  into  a  character  string.  The 
returned  string  is  in  a  static  area  and  must  not  be  modified.  If  the  specified  keysym  is  not 
defined,  XKeysymToString  returns  NULL.  For  example,  XKeysymToString  converts 
XK_Shift  to  "Shift". 

Note  that  XKeysymString  does  not  return  the  string  that  is  mapped  to  the  keysym,  but  only  a 
string  version  of  the  keysym  itself.  In  other  words,  even  if  the  Fl  key  is  mapped  to  the  string  "- 
STOP"  using  XRebindKeysym,  XKeysymToString  still  returns  "Fl".  XLookupString, 
however,  would  return  "STOP". 

In  Release  4,  XKeysymToString  can  process  keysyms  that  are  not  defined  by  the  Xlib  stan 
dard.  Note  that  the  set  of  keysyms  that  are  available  in  this  manner  and  the  mechanisms  by 
which  Xlib  obtains  them  is  implementation  dependent.  (In  the  MIT  sample  implementation, 
the  resource  file  lusrlliblXl  1  IXKeysymDB  is  used  starting  in  Release  4.  The  keysym  name  is 
used  as  the  resource  name,  and  the  resource  value  is  the  keysym  value  in  uppercase  hexade 
cimal.) 

Related  Commands 

IsCursorKey,  IsFunctionKey, IsKeypadKey,  IsMiscFunctionKey, Is- 
Modif ierKey, IsPFKey,  XChangeKeyboardMapping, XDeleteModif iermap- 
Entry, XFreeModif iermap,  XGetKeyboardMapping,  XGetModif ierMapping, 
XInsertModif iermapEntry, XKeycodeToKeysym,  XKeysymToKeycode, 
XLookupKeysym,  XLookupString, XNewModif ierMap,  XQueryKeymap,  XRebind 
Keysym,  XRef reshKeyboardMapping, XSetModif ierMapping,  XStringTo- 
Keysym. 
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/ 


XKIIICIient 


Name 

XKillClient  —  destroy  a  client  or  its  remaining  resources. 

Synopsis 

XKillClient  (display,  resource) 
Display  *  display; 
XID  resource; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

resource          Specifies  any  resource  created  by  the  client  you  want  to  destroy,  or  the  con 
stant  AllTemporary. 

Description 

If  a  valid  resource  is  specified,  XKillClient  forces  a  close-down  of  the  client  that  created 
the  resource.  If  the  client  has  already  terminated  in  either  RetainPermanent  or  Retain- 
Temporary  mode,  all  of  the  client's  resources  are  destroyed.  If  AllTemporary  is  specified 
in  the  resource  argument,  then  the  resources  of  all  clients  that  have  terminated  in  Retain- 
Temporary  are  destroyed. 

For  more  information,  see  Volume  One,  Chapter  13,  Other  Programming  Techniques. 

Errors 

BadValue 

Related  Commands 

XSetCloseDownMode. 
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XLiStDepthS  \ x,ib-W,ndowManagerH,ms- 

Name 

XListDepths  —  determine  the  depths  available  on  a  given  screen. 

Synopsis 

int  *XListDepths (display,  screen_n umber,  count) 
Display  *display; 
int  screen_n umber; 
int  *  count;     /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

s c r e en_n umb e r 

Specifies  the  appropriate  screen  number  on  the  host  server. 

count  Returns  the  number  of  depths. 

Availability 

Release  4  and  later. 

Description 

XListDepths  returns  the  array  of  depths  that  are  available  on  the  specified  screen.  If  the 
specified  screen_n umber  is  valid  and  sufficient  memory  for  the  array  can  be  allocated, 
XListDepths  sets  count  to  the  number  of  available  depths.  Otherwise,  it  does  not  set 
count  and  returns  NULL.  To  release  the  memory  allocated  for  the  array  of  depths,  use  XFree. 

Related  Commands 

DefaultDepthOf  Screen  macro,  Def  aultDepth  macro,  XListPixmapFormats. 
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-Xlib-  Extensions /  XLiStExtensiOHS 

Name 

XListExtensions  —  return  a  list  of  all  extensions  to  X  supported  by  Xlib  and  the  server. 

Synopsis 

char  **XListExtensions  ( display,  nextensions) 
Display  *disp_Zay; 
int  *nextensions;         /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

nextensions  Returns  the  number  of  extensions  in  the  returned  list. 

Description 

XListExtensions  lists  all  the  X  extensions  supported  by  Xlib  and  the  current  server.  The 
returned  strings  will  be  in  ISO  LATIN- 1  encoding,  which  means  that  the  first  128  character 
codes  are  ASCII,  and  the  second  128  character  codes  are  for  special  characters  needed  in  west 
ern  languages  other  than  English. 

For  more  information  on  extensions,  see  Volume  One,  Chapter  13,  Other  Programming  Tech 
niques. 

Related  Commands 

XFreeExtensionList, XQueryExtension. 
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XListFonts  "\ 


•Xlib- Fonts- 


Name 

XListFonts  —  return  a  list  of  the  available  font  names. 

Synopsis 

char  **XListFonts ( display,  pattern,  maxnames,  actual_count) 
Display  *  display; 
char  * pattern; 
int  maxnames ; 
int  *  actual_count ;         /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

pattern  Specifies  the  string  associated  with  the  font  names  you  want  returned.  You 

can  specify  any  string,  including  asterisks  (*),  and  question  marks.  The  aster 
isk  indicates  a  wildcard  for  any  number  of  characters  and  the  question  mark 
indicates  a  wildcard  for  a  single  character.  Upper  or  lower  case  is  not  impor 
tant.  The  string  should  be  in  ISO  LATIN- 1  encoding,  which  means  that  the 
first  128  character  codes  are  ASCII,  and  the  second  128  character  codes  are 
for  special  characters  needed  in  western  languages  other  than  English. 

maxnames         Specifies  the  maximum  number  of  names  that  are  to  be  in  the  returned  list. 

actual_count 

Returns  the  actual  number  of  font  names  in  the  list. 

Description 

XListFonts  returns  a  list  of  font  names  that  match  the  string  pattern.  Each  returned  font 
name  string  is  terminated  by  NULL  and  is  lower  case.  The  maximum  number  of  names  returned 
in  the  list  is  the  value  you  passed  to  maxnames.  The  function  returns  the  actual  number  of 
font  names  in  actual_count. 

If  no  fonts  match  the  specified  names,  XListFonts  returns  NULL. 

The  client  should  call  XFreeFontNames  when  done  with  the  font  name  list. 

The  font  search  path  (the  order  in  which  font  names  in  various  directories  are  compared  to 
pat  tern)  is  set  by  XSetFontPath. 

For  more  information  on  fonts,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty,  XListFontsWithlnf o,  XLoad- 
Font,  XLoadQueryFont, XQueryFont, XSetFont,  XSetFontPath,  XUnloadFont. 
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-xnb-  Fonts J  XListFontsWithlnfo 

Name 

XListFontsWithlnfo  —  obtain  the  names  and  information  about  loaded  fonts. 

Synopsis 

char  **XListFontsWithInfo(  display,  pattern,  maxnames, 

count,  info) 
Display  *disp_Zay; 

char  *pattern;  /*  null-terminated  */ 

int  maxnames; 

int  *  count;  /*  RETURN  */ 

XFontStruct  **info;        /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

pattern  Specifies  the  string  associated  with  the  font  names  you  want  returned.  You 

can  specify  any  string,  including  asterisks  (*)  and  question  marks.  The  aster 
isk  indicates  a  wildcard  on  any  number  of  characters  and  the  question  mark 
indicates  a  wildcard  on  a  single  character.  Upper  or  lower  case  is  not  impor 
tant.  The  string  should  be  in  ISO  LATIN- 1  encoding,  which  means  that  the 
first  128  character  codes  are  ASCII,  and  the  second  128  character  codes  are 
for  special  characters  needed  in  western  languages  other  than  English. 

maxnames          Specifies  the  maximum  number  of  names  that  are  to  be  in  the  returned  list. 
count  Returns  the  actual  number  of  matched  font  names. 

info  Returns  a  pointer  to  a  list  of  font  information  structures.   XListFonts 

Withlnfo  provides  enough  space  for  maxnames  pointers. 

Description 

XListFontsWithlnfo  returns  a  list  of  font  names  that  match  the  specified  pattern  and  a 
also  returns  limited  information  about  each  font  that  matches.  The  list  of  names  is  limited  to 
the  size  specified  by  the  maxnames  argument  The  list  of  names  is  in  lower  case. 

XListFontsWithlnfo  returns  NULL  if  no  matches  were  found. 

To  free  the  allocated  name  array,  the  client  should  call  XFreeFont Names.  To  free  the  font 
information  array,  the  client  should  call  XFreeFont  Info. 

The  information  returned  for  each  font  is  identical  to  what  XQueryFont  would  return,  except 
that  the  per-character  metrics  (Ibearing,  rbearing,  width,  ascent,  descent  for 
single  characters)  are  not  returned. 

The  font  search  path  (the  order  in  which  font  names  in  various  directories  are  compared  to 
pattern)  is  set  by  XSetFontPath.  XListFonts  returns  NULL  if  no  matches  were  found. 

For  more  information  on  fonts,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
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XListFontsWithlnfo 


(continued) 


Xlib  -  Fonts 


Structures 

typedef  struct  { 

XExtData  *ext_data;  /* 

Font  fid;  /* 

unsigned  direction;  /* 
unsigned  min_char_or_byte2;  /* 
unsigned  max_char_or_byte2;  /* 

unsigned  min  bytel;  /* 

unsigned  max_bytel;  /* 

Bool  all_chars  exist;  /* 

unsigned  default_char;  /* 

int  n_properties;  /* 

XFontProp  *properties;  /* 

XCharStruct  min  bounds;  /* 

XCharStruct  max_bounds;  /* 

XCharStruct  *per_char;  /* 

int  ascent;  /* 

int  descent;  /* 

}  XFontStruct; 


hook  for  extension  to  hang  data  */ 

Font  ID  for  this  font  */ 

hint  about  direction  the  font  is  painted  */ 

first  character  */ 

last  character  */ 

first  row  that  exists  */ 

last  row  that  exists  */ 

flag  if  all  characters  have  nonzero  size*/ 

char  to  print  for  undefined  character  */ 

how  many  properties  there  are  */ 

pointer  to  array  of  additional  properties*/ 

minimum  bounds  over  all  existing  char*/ 

minimum  bounds  over  all  existing  char*/ 

first_char  to  last_char  information  */ 

logical  extent  above  baseline  for  spacing  */ 

logical  descent  below  baseline  for  spacing  */ 


Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath,  XGetFontPath, XGetFontProperty, XListFonts,  XLoadFont, 
XLoadQueryFont, XQueryFont, XSetFont,  XSetFontPath, XUnloadFont. 
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_X,ib  -  Host  Access /  XLJStHOStS 

Name 

XListHosts  —  obtain  a  list  of  hosts  having  access  to  this  display. 

Synopsis 

XHost Address    *XListHosts (display,    nhosts,    state) 
Display    * display ; 

int    *nhosts;  /*  RETURN    */ 

Bool    *state;  /*  RETURN    */ 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD  i  sp  1  ay . 

nhosts  Returns  the  number  of  hosts  currently  in  the  access  control  list. 

state  Returns  whether  the  access  control  list  is  currently  being  used  by  the  server  to 

process  new  connection  requests  from  clients.   True  if  enabled,  False  if 
disabled. 

Description 

XListHosts  returns  the  current  access  control  list  as  well  as  whether  the  use  of  the  list  is 
enabled  or  disabled.  XListHosts  allows  a  program  to  find  out  what  machines  make  connec 
tions,  by  looking  at  a  list  of  host  structures.  This  XHost  Address  list  should  be  freed  when  it 
is  no  longer  needed.  XListHosts  returns  NULL  on  failure. 

For  more  information  on  access  control  lists,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques, 

Structures 

typedef  struct  { 

int  family; 

int  length; 

char  *address; 
}  XHostAddress; 

Related  Commands 

XAddHost, XAddHosts, XDisableAccessControl,  XEnableAccessControl, 
XRemoveHost, XRemoveHosts, XSetAccessControl. 


Xlib  Reference  Manual  2" 


XListlnstalledColormaps  \ X|lb  _  Colormaps_ 

Name 

XListlnstalledColormaps  —  get  a  list  of  installed  colormaps. 

Synopsis 

Colormap   *XListInstalledColormaps ( display,    w,    num) 
display   * display ; 
Window    w; 
int    *num;  /*  RETURN    */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  for  whose  screen  you  want  the  list  of  currently 

installed  colormaps. 

num  Returns  the  number  of  currently  installed  colormaps  in  the  returned  list. 

Description 

XListlnstalledColormaps  returns  a  list  of  the  currently  installed  colormaps  for  the 
screen  containing  the  specified  window.  The  order  in  the  list  is  not  significant.  There  is  no  dis 
tinction  in  the  list  between  colormaps  actually  being  used  by  windows  and  colormaps  no  longer 
in  use  which  have  not  yet  been  freed  or  destroyed. 

XListlnstalledColormaps  returns  None  and  sets  num  to  zero  on  failure. 

The  allocated  list  should  be  freed  using  XFree  when  it  is  no  longer  needed. 

For  more  information  on  installing  colormaps,  see  Volume  One,  Chapter  7,  Color. 

Errors 

BadWindow 

Related  Commands 

Def aultColormap, DisplayCells, XCopyColormapAndFree, XCreate- 
Colormap, XFreeColormap, XGetStandardColormap, XInstallColormap, 
XSetStandardColormap, XSetWindowColormap,  XUninstallColormap. 
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-Xllb-  Window  Manager  Hints /  XLJStPixmapFormatS 

Name 

XListPixmapFormats  —  obtain  the  supported  pixmap  formats  for  a  given  server. 

Synopsis 

XPixmapFormat Values  *XListPixmapFormats {  display,  count) 
Display  ^display; 
int  *  count;     /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

count  Returns  the  number  of  pixmap  formats  that  are  supported  by  the  server. 

Availability 

Release  4  and  later. 

Description 

XListPixmapFormats  returns  an  array  of  XPixmapFormatValues  structures  that 
describe  the  types  of  Z  format  images  that  are  supported  by  the  specified  server.  If  insufficient 
memory  is  available,  XListPixmapFormats  returns  NULL.  To  free  the  allocated  storage  for 
the  XPixmapFormatValues  structures,  use  XFree. 

Structures 

typedef  struct  { 

int  depth; 

int  bits_per_pixel; 

int  scanline_pad; 
}  XPixmapFormatValues; 

Related  Commands 

XListDepths. 
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XListProperties  \, 

^ Xlib  -  Properties- 
Name 

XListProperties  —  get  the  property  list  for  a  window. 

Synopsis 

Atom   *XListProperties ( display,    w,    num_prop) 
Display   *display; 
Window   w; 
int    *num_jprop;  /*  RETURN    */ 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD  i  sp  1  ay . 

w  Specifies  the  window  whose  property  list  you  want. 

num_prop         Returns  the  length  of  the  properties  array. 

Description 

XListProperties  returns  a  pointer  to  an  array  of  atoms  for  properties  that  are  defined  for 
the  specified  window.  XListProperties  returns  NULL  on  failure  (when  window  w  is  inva 
lid). 

To  free  the  memory  allocated  by  this  function,  use  XFree. 

For  more  information,  see  Volume  One,  Chapter  IQJnterclient  Communication. 

Errors 

BadWindow 

Related  Commands 

XChangeProperty, XDeleteProperty, XGetAtomName, XGetFontProperty, 
XGetWindowProperty,  XInternAtom,  XRotateWindowProperties, XSet- 
StandardProperties. 
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-xiib  -  Fonts /  XLoadFont 

Name 

XLoadFont  —  load  a  font  if  not  already  loaded;  get  font  ID. 

Synopsis 

Font  XLoadFont (display,  name) 
Display  *display; 
char  *name; 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD i splay. 

name  Specifies  the  name  of  the  font  in  a  null  terminated  string.  As  of  Release  4,  the 

*  and  ?  wildcards  are  allowed  and  may  be  supported  by  the  server.  Upper  or 
lower  case  is  not  important.  The  string  should  be  in  ISO  LATIN- 1  encoding, 
which  means  that  the  first  128  character  codes  are  ASCII,  and  the  second  128 
character  codes  are  for  special  characters  needed  in  western  languages  other 
than  English. 

Description 

XLoadFont  loads  a  font  into  the  server  if  it  has  not  already  been  loaded  by  another  client. 
XLoadFont  returns  the  font  ID  or,  if  it  was  unsuccessful,  generates  a  BadName  error.  When 
the  font  is  no  longer  needed,  the  client  should  call  xunloadFont.  Fonts  are  not  associated 
with  a  particular  screen.  Once  the  font  ID  is  available,  it  can  be  set  in  the  font  member  of  any 
GC,  and  thereby  used  in  subsequent  drawing  requests. 

Font  information  is  usually  necessary  for  locating  the  text.  Call  XLoadFontwithinf  o  to 
get  the  info  at  the  time  you  load  the  font,  or  call  XQueryFont  if  you  used  XLoadFont  to 
load  the  font. 

For  more  information  on  fonts,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Errors 

BadAlloc          Server  has  insufficient  memory  to  store  font. 

BadName  name  specifies  an  unavailable  font 

Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o,  XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts,  XListFontsWith- 
Inf o,  XLoadQueryFont, XQueryFont, XSetFont,  XSetFontPath,  XUnloadFont. 
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XLoadQueryFont  , x,,b-Fon,s- 

Name 

XLoadQueryFont  —  load  a  font  and  fill  information  structure. 

Synopsis 

XFontStruct  *XLoadQueryFont ( display,  name) 
Display  *display; 
char  *name; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

name  Specifies  the  name  of  the  font.  This  name  is  a  null  terminated  string.  As  of 

Release  4,  the  *  and  ?  wildcards  are  allowed  and  may  be  supported  by  the 
server.  Upper  or  lower  case  is  not  important. 

Description 

XLoadQueryFont  performs  an  XLoadFont  and  XQueryFont  in  a  single  operation.  XLoad 
QueryFont  provides  the  easiest  way  to  get  character-size  tables  for  placing  a  proportional  font. 
That  is,  XLoadQueryFont  both  opens  (loads)  the  specified  font  and  returns  a  pointer  to  the 
appropriate  XFontStruct  structure.  If  the  font  does  not  exist,  XLoadQueryFont  returns  NULL. 

The  XFontStruct  structure  consists  of  the  font-specific  information  and  a  pointer  to  an  array 
of  xchar struct  structures  for  each  character  in  the  font. 

For  more  information  on  fonts,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Errors 

BadAl loc  server  has  insufficient  memory  to  store  font 

BadName  name  specifies  an  unavailable  font 

Structures 

typedef  struct  { 

XExtData  *ext_data;  /*  hook  for  extension  to  hang  data  */ 

Font  fid;  /*  Font  ID  for  this  font  */ 

unsigned  direction;  /*  hint  about  direction  the  font  is  painted  */ 

unsigned  min_char_or_byte2;  /*  first  character  */ 

unsigned  max_char_or_byte2;  /*  last  character  */ 

unsigned  min_bytel;  /*  first  row  that  exists  */ 

unsigned  max_bytel;  /*  last  row  that  exists  */ 

Bool  all_chars_exist;  /*  flag  if  all  characters  have  nonzero  size*/ 

unsigned  default_char;  /*  char  to  print  for  undefined  character  */ 

int  n_properties;  /*  how  many  properties  there  are  */ 

XFontProp  *properties;  /*  pointer  to  array  of  additional  properties*/ 

XCharStruct  min_bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  max_bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  *per_char;  /*  first_char  to  last_char  information  */ 

int  ascent;  /*  logical  extent  above  baseline  for  spacing  */ 

int  descent;  /*  logical  descent  below  baseline  for  spacing  */ 

}  XFontStruct; 
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(continued) 


XLoadQueryFont 


typedef  struct  { 

short  Ibearing;  /* 

short  rbearing;  /* 

short  width;  /* 

short  ascent;  /* 

short  descent;  /* 
unsigned  short  attributes;   /* 

}  XCharStruct; 


origin  to  left  edge  of  character  */ 
origin  to  right  edge  of  character  */ 
advance  to  next  char's  origin  */ 
baseline  to  top  edge  of  character  */ 
baseline  to  bottom  edge  of  character 
per  char  flags  (not  predefined)  */ 


Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath,  XGetFontPath, XGetFontProperty,  XListFonts,  XListFontsWith- 
Info,  XLoadFont, XQueryFont, XSetFont,  XSetFontPath, XUnloadFont. 
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XLookllpAssoc  A 


XI ib  -  Association  Tables  — 


Name 

XLookUpAssoc  —  obtain  data  from  an  association  table. 

Synopsis 

caddr_t  XLookUpAssoc ( display,  table,  x_id) 
Display  *display; 
XAssocTable  *  table; 
XID  x_id; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XQpenD  i  sp  1  ay . 

t  abl  e  Specifies  the  association  table. 

x_i  d  Specifies  the  X  resource  ID. 

Description 

This  function  is  provided  for  compatibility  with  X  Version  10.  To  use  it  you  must  include  the 
file  <XlllX10.h>  and  link  with  the  library  -loldX. 

Association  tables  provide  a  way  of  storing  data  locally  and  accessing  by  ID.  XLookUp 
Assoc  retrieves  the  data  stored  in  an  XAssocTable  by  its  XID.  If  the  matching  XID  can  be 
found  in  the  table,  the  routine  returns  the  data  associated  with  it.  If  the  x_i  d  cannot  be  found 
in  the  table  the  routine  returns  NULL. 

For  more  information  on  association  tables,  see  Volume  One,  Appendix  B,X10  Compatibility. 
Structures 

typedef  struct  { 

XAssoc  ^buckets;        /*  pointer  to  first  bucket  in  bucket  array  */ 
int  size;  /*  table  size  (number  of  buckets)  */ 

}  XAssocTable; 

typedef  struct  _XAssoc  { 

struct  _XAssoc  *next;  /*  next  object  in  this  bucket  */ 

struct  _XAssoc  *prev;  /*  previous  object  in  this  bucket  */ 

Display  *display;  /*  display  which  owns  the  ID  */ 

XID  x_id;  /*  X  Window  System  ID  */ 

char  *data;  /*  pointer  to  untyped  memory  */ 

}  XAssoc; 

Related  Commands 

XCreateAssocTable, XDeleteAssoc, XDestroyAssocTable, XMakeAssoc. 
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—  Xllb- Color  Cells- 


j  XLookupColor 


Name 

XLookupColor  —  get  database  RGB  values  and  closest  hardware-supported  RGB  values  from 
color  name. 

Synopsis 

Status  XLookupColor ( display,  cmapf  colorname,  rgb_db_deff 

hardware_def) 
Display  ^display; 
Colormap  cmap ; 
char  * colorname ; 
XColor  *rgb_db_defr  *hardware_def ;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

cmap  Specifies  the  colormap. 

colorname  Specifies  a  color  name  string  (for  example  "red").  Upper  or  lower  case 

does  not  matter.  The  string  should  be  in  ISO  LATIN  1  encoding,  which 
means  that  the  first  128  character  codes  are  ASCII,  and  the  second  128 
character  codes  are  for  special  characters  needed  in  western  languages 
other  than  English. 

rgb_db_def          Returns  the  exact  RGB  values  for  the  specified  color  name  from  the 
lusrlliblXlllrgb  database. 

hardware_def      Returns  the  closest  RGB  values  possible  on  the  hardware. 

Description 

XLookupColor  looks  up  RGB  values  for  a  color  given  the  colorname  string.  It  returns  both 
the  exact  color  values  and  the  closest  values  possible  on  tthe  screen  specified  by  cmap. 

XLookupColor  returns  nonzero  if  colorname  exists  in  the  RGB  database  or  zero  if  it  does 
not  exist. 

To  determine  the  exact  RGB  values,  XLookupColor  uses  a  database  on  the  X  server.  On 
UNIX,  this  database  is  lusrlliblXlllrgb,  To  read  the  colors  provided  by  the  database  on  a 
UNIX-based  system,  see  lusrlliblXlllrgb.txt.  The  location,  name,  and  contents  of  this  file  are 
server-dependent. 

For  more  information  see  Volume  One,  Chapter  7,  Color,  and  Appendix  D,  The  Color  Data 
base,  in  this  volume. 
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XLOQkupColor  (continued)  Xlib  -  Color  Cells 

Errors 

BadName  Color  name  not  in  database. 

BadColormap  Specified  colormap  invalid. 
Structures 

typedef  struct  { 

unsigned  long  pixel; 

unsigned  short  red,  green,  blue; 

char  flags;  /*  DoRed,  DoGreen,  DoBlue  */ 

char  pad; 
}  XColor; 

Related  Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor- 
Planes,  XAllocNamedColor, XFreeColors, XParseColor, XQueryColor, 
XQueryColors, XStoreColor, XStoreColors,  XStoreNamedColor. 
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—  Xlib -Keyboard  • 


J  XLookupKeysym 


Name 

XLookupKeysym  —  get  the  keysym  corresponding  to  a  keycode  in  structure. 

Synopsis 

KeySym  XLookupKeysym ( event,  index) 
XKeyEvent  * event ; 
int  index; 

Arguments 

event  Specifies  the  KeyPress  or  KeyRelease  event  that  is  to  be  used. 

index  Specifies  which  keysym  from  the  list  associated  with  the  keycode  in  the  event  to 

return.  These  correspond  to  the  modifier  keys,  and  the  symbols  ShiftMap- 
Index,  LockMapIndex,  ControlMapIndex,  ModlMapIndex,  Mod2- 
Maplndex,  ModSMapIndex,  Mod4MapIndex,  and  ModSMapIndex  can  be 
used. 

Description 

Given  a  keyboard  event  and  the  index  into  the  list  of  keysyms  for  that  keycode,  XLookup 
Keysym  returns  the  keysym  from  the  list  that  corresponds  to  the  keycode  in  the  event.  If  no 
keysym  is  defined  for  the  keycode  of  the  event,  XLookupKeysym  returns  NoSymbol. 

Each  keycode  may  have  a  list  of  associated  keysyms,  which  are  portable  symbols  representing 
the  meanings  of  the  key.  The  index  specifies  which  keysym  in  the  list  is  desired,  indicating 
the  combination  of  modifier  keys  that  are  currently  pressed.  Therefore,  the  program  must  inter 
pret  the  state  member  of  the  XKeyEvent  structure  to  determine  the  index  before  calling 
this  function.  The  exact  mapping  of  modifier  keys  into  the  list  of  keysyms  for  each  keycode  is 
server-dependent  beyond  the  fact  that  the  first  keysym  corresponds  to  the  keycode  without 
modifier  keys,  and  the  second  corresponds  to  the  keycode  with  Shift  pressed. 

XLookupKeysym  simply  calls  XKeycodeToKeysym,  using  arguments  taken  from  the  speci 
fied  event  structure. 

Structures 

typedef  struct  { 

int  type;  /*  of  event  */ 

unsigned  long  serial;    /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;  /*  true  if  this  came  from  a  SendEvent  request  */ 

Display  ^display;     /*  display  the  event  was  read  from  */ 

Window  window;        /*  "event"  window  it  is  reported  relative  to  */ 

Window  root;          /*  root  window  that  the  event  occured  on  */ 

Window  subwindow;     /*  child  window  */ 

Time  time;  /*  milliseconds  */ 

int  x,  y;  /*  pointer  x,  y  coordinates  in  event  window  */ 

int  x  root,  y  root;   /*  coordinates  relative  to  root  */ 

unsigned  int  state;   /*  key  or  button  mask  */ 

unsigned  int  keycode;  /*  detail  */ 

Bool  same_screen;     /*  same  screen  flag  */ 

}  XKeyEvent; 
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Related  Commands 

XChangeKeyboardMapping,  XDeleteModif  iermapEntry,  XFreeModif  iermap, 
XGetKeyboardMapping, XGetModif ierMapping,  XInsertModif iermapEntry, 
XKeycodeToKeysym,  XKeysymToKeycode, XKeysymToString,  XLookupString, 
XNewModif ierMap, XQueryKeymap, XRebindKeysym,  XRef reshKeyboard- 
Mapping, XSetModif ierMapping, XStringToKeysym. 
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—Xlib -Keyboard  • 


J  XLookupString 


Name 

XLookupString  —  map  a  key  event  to  ASCH  string,  keysym,  and  ComposeStatus. 

Synopsis 

int  XLookupString ( event,  buffer,  num_bytes,  keysym,  status) 
XKeyEvent  *event; 

char  * buffer;  /*  RETURN  */ 

int  num_bytes ; 

KeySym  *  keysym;  /*  RETURN  */ 

XComposeStatus  *status;    /*  not  implemented  */ 

Arguments 

event  Specifies  the  key  event  to  be  used. 

buffer  Returns  the  resulting  string. 

num_bytes        Specifies  the  length  of  the  buffer.  No  more  than  num_bytes  of  translation 
are  returned. 

keysym  If  this  argument  is  not  NULL,  it  specifies  the  keysym  ID  computed  from  the 

event. 

status  Specifies  the  XCompose  structure  that  contains  compose  key  state  informa 

tion  and  that  allows  the  compose  key  processing  to  take  place.  This  can  be 
NULL  if  the  caller  is  not  interested  in  seeing  compose  key  sequences.  Not 
implemented  in  X  Consortium  Xlib  through  Release  4. 

Description 

XLookupString  gets  an  ASCH  string  and  a  keysym  that  are  currently  mapped  to  the  keycode 
in  a  KeyPress  or  KeyRelease  event,  using  the  modifier  bits  in  the  key  event  to  deal  with 
shift,  lock  and  control.  The  XLookupString  return  value  is  the  length  of  the  translated 
string  and  the  string's  bytes  are  copied  into  buffer.  The  length  may  be  greater  than  1  if  the 
event's  keycode  translates  into  a  keysym  that  was  rebound  with  XRebindKeysym. 

The  compose  status  is  not  implemented  in  any  release  of  the  X  Consortium  version  of  Xlib 
through  Release  4. 

In  Release  4,  XLookupString  implements  the  new  concept  of  keyboard  groups.  Keyboard 
groups  support  having  two  complete  sets  of  keysyms  for  a  keyboard.  Which  set  will  be  used 
can  be  toggled  using  a  particular  key.  This  is  implemented  by  using  the  first  two  keysyms  in 
the  list  for  a  key  as  one  set,  and  the  next  two  keysyms  as  the  second  set.  For  more  information 
on  keyboard  groups,  see  Volume  One,  Appendix  G,  Release  Notes. 

For  more  information  on  using  XLookupString  in  general,  see  Volume  One,  Chapter  9,  The 
Keyboard  and  Pointer. 

Structures 

/* 

*  Compose  sequence  status  structure,  used  in  calling  XLookupString. 
*/ 
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typedef  struct  _XComposeStatus  { 

char  *compose_ptr;    /*  state  table  pointer  */ 

int  chars_matched;    /*  match  state  */ 
}  XComposeStatus; 

typedef  struct  { 

int  type;  /*  of  event  */ 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;  /*  true  if  this  came  from  a  SendEvent  request  */ 

isplay  'display;  /*  Display  the  event  was  read  from  */ 

Window  window;  /*  "event"  window  it  is  reported  relative  to  */ 

Window  root;  /*  root  window  that  the  event  occured  on  */ 

Window  subwindow;  /*  child  window  */ 

Time  time;  /*  milliseconds  */ 

L  x/  y;  /*  Pointer  x,  y  coordinates  in  event  window  */ 

int  x_root,  y_root;  /*  coordinates  relative  to  root  */ 

unsigned  int  state;  /*  key  or  button  mask  */ 

unsigned  int  keycode;  /*  detail  */ 

Bool  same_screen;  /*  same  screen  flag  */ 
}  XKeyEvent; 

Related  Commands 

XChangeKeyboardMapping,XDeleteModifiermapEntry,XFreeModifiermap 

XGetKeyboardMapping,XGetModifierMaPping,XInsertModifiermaPEntry' 

<eycodeToKeysym,  XKeysymToKeycode,  XKeysymToString,  XLookupKeysym' 

f  ierMap,  XQueryKeymap,  XRebindKeySym,  XRef reshKeyboard- 
Mapping, XSetModif ierMapping,  XStringToKeysym. 
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Name 

XLowerWindow  —  lower  a  window  in  the  stacking  order. 

Synopsis 

XLowerWindow  ( display,    w) 
Display    *display; 
Window   w; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  ID  of  the  window  to  be  lowered. 

Description 

XLowerWindow  lowers  a  window  in  the  stacking  order  of  its  siblings  so  that  it  does  not 
obscure  any  sibling  windows.  If  the  windows  are  regarded  as  overlapping  sheets  of  paper 
stacked  on  a  desk,  then  lowering  a  window  is  analogous  to  moving  the  sheet  to  the  bottom  of 
the  stack,  while  leaving  its  x  and  y  location  on  the  desk  constant.  Lowering  a  mapped  window 
will  generate  exposure  events  on  any  windows  it  formerly  obscured. 

If  the  override_redirect  attribute  of  the  window  (see  Chapter  4,  Window  Attributes)  is 
False  and  the  window  manager  has  selected  SubstructureRedirectMask  on  the  par 
ent,  then  a  Conf  igureRequest  event  is  sent  to  the  window  manager,  and  no  further  pro 
cessing  is  performed.  Otherwise,  the  window  is  lowered  to  the  bottom  of  the  stack. 

LeaveNotify  events  are  sent  to  the  lowered  window  if  the  pointer  was  inside  it,  and 
EnterNotif  y  events  are  sent  to  the  window  which  was  immediately  below  the  lowered  win 
dow  at  the  pointer  position. 

For  more  information,  see  Volume  One,  Chapter  14,  Window  Management. 

Errors 

BadWindow 

Related  Commands 

XCirculateSubwindows, XCirculateSubwindowsDown,  XCirculate- 
SubwindowsUp,  XConf  igureWindow,  XMoveResizeWindow,  XMoveWindow, 
XQueryTree, XRaiseWindow, XReparentWindow,  XResizeWindow,  XRestack- 
Windows. 
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XMakeAssoc  \ X||b  _  Assoc|atlon  Tab|es_ 

Name 

XMakeAssoc  —  create  an  entry  in  an  association  table. 

Synopsis 

XMakeAssoc ( display,  table,  x_idf  data) 
Display  * display; 
XAssocTable  * table; 
XID  x_id; 
caddr_t  data; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  xopenDi splay. 

tabl  e  Specifies  the  association  table  in  which  an  entry  is  to  be  made. 

x_i  d  Specifies  the  X  resource  ID. 

data  Specifies  the  data  to  be  associated  with  the  X  resource  ID. 

Description 

XMakeAssoc  inserts  data  into  an  XAssocTable  keyed  on  an  XID.  Association  tables  allow 
you  to  easily  associate  data  with  resource  ID's  for  later  retrieval.  Association  tables  are  local, 
accessible  only  by  this  client. 

This  function  is  provided  for  compatibility  with  X  Version  10.  To  use  it  you  must  include  the 
file  <Xll/X10.h>  and  link  with  the  library  -loldX. 

Data  is  inserted  into  the  table  only  once.  Redundant  inserts  are  meaningless  and  cause  no  prob 
lems.  The  queue  in  each  association  bucket  is  sorted  from  the  lowest  XID  to  the  highest  XID. 

For  more  information,  see  Volume  One,  Appendix  B,X70  Compatibility. 
Structure 

typedef  struct  { 

XAssoc  *buckets;        /*  pointer  to  first  bucket  in  bucket  array  */ 
int  size;  /*  table  size  (number  of  buckets)  */ 

}  XAssocTable; 

typedef  struct  _XAssoc  { 

struct  _XAssoc  *next;  /*  next  object  in  this  bucket  */ 

struct  _XAssoc  *prev;  /*  previous  object  in  this  bucket  */ 

Display  *display;  /*  display  which  owns  the  ID  */ 

XID  x_id;  /*  X  Window  System  ID  * / 

char  *data;  /*  pointer  to  untyped  memory  */ 

}  XAssoc; 

Related  Commands 

XCreateAssocTable, XDeleteAssoc, XDestroyAssocTable, XLookUpAssoc. 
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— Xlib  -  Window  Mapping  • 


J  XMapRaised 


Name 

XMapRaised  —  map  a  window  on  top  of  its  siblings. 

Synopsis 

XMapRaised ( display,  w) 
Display  * display ; 
Window  w; 

Arguments 

di  spl  ay        Specifies  a  connection  to  an  X  server;  returned  from  XOpenD i  sp  1  ay . 

w  Specifies  the  window  ID  of  the  window  to  be  mapped  and  raised. 

Description 

XMapRaised  marks  a  window  as  eligible  to  be  displayed.  It  will  actually  be  displayed  if  its 
ancestors  are  mapped,  it  is  on  top  of  sibling  windows,  and  it  is  not  obscured  by  unrelated  win 
dows.  XMapRaised  is  similar  to  XMapWindow,  except  it  additionally  raises  the  specified 
window  to  the  top  of  the  stack  among  its  siblings.  Mapping  an  already  mapped  window  with 
XMapRaised  raises  the  window.  See  XMapWindow  for  further  details. 

For  more  information,  see  Volume  One,  Chapter  14,  Window  Management. 
Errors 

BadWindow 

Related  Commands 

XMapSubwindows,  XMapWindow,  XUnmapSubwindows,  XUnmapWindow. 
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XMapSubwindows 

Xlib  -  Window  Mapping- 
Name 

XMapSubwindows  —  map  all  subwindows  of  window. 

Synopsis 

XMapSubwindows ( display,  w) 
Display  *  display; 
Window  w; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  ID  of  the  window  whose  subwindows  are  to  be  mapped. 

Description 

XMapSubwindows  maps  all  subwindows  of  a  window  in  top-to-bottom  stacking  order. 
XMapSubwindows  also  generates  an  Expose  event  on  each  newly  displayed  window.  This 
is  much  more  efficient  than  mapping  many  windows  one  at  a  time,  as  much  of  the  work  need 
only  be  performed  once  for  all  of  the  windows  rather  than  for  each  window.  XMap 
Subwindows  is  not  recursive  —  it  does  not  map  the  subwindows  of  the  subwindows. 

For  more  information,  see  Volume  One,  Chapter  14,  Window  Management. 
Errors 

BadWindow 

Related  Commands 

XMapRaised,  XMapWindow,  XUnmapSubwindows,  XUnmapWindow. 
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-Xlib  -  Window  Mapping '  XMapWindOW 

Name 

XMapWindow  —  map  a  window. 

Synopsis 

XMapWindow  (display,    w) 
Display    * display ; 
Window   w; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  to  be  mapped. 

Description 

XMapWindow  maps  a  window,  making  it  eligible  for  display  depending  on  its  stacking  order 
among  its  siblings,  the  mapping  status  of  its  ancestors,  and  the  placement  of  other  visible  win 
dows.  If  all  the  ancestors  are  mapped,  and  it  is  not  obscured  by  siblings  higher  in  the  stacking 
order,  the  window  and  all  of  its  mapped  subwindows  are  displayed. 

Mapping  a  window  that  has  an  unmapped  ancestor  does  not  display  the  window  but  marks  it  as 
eligible  for  display  when  its  ancestors  become  mapped.  Mapping  an  already  mapped  window 
has  no  effect  (it  does  not  raise  the  window). 

Note  that  for  a  top-level  window,  the  window  manager  may  intervene  and  delay  the  mapping  of 
the  window.  The  application  must  not  draw  until  it  has  received  an  Expose  event  on  the  win 
dow. 

If  the  window  is  opaque,  XMapWindow  generates  Expose  events  on  each  opaque  window 
that  it  causes  to  become  displayed.  If  the  client  first  maps  the  window,  then  paints  the  window, 
then  begins  processing  input  events,  the  window  is  painted  twice.  To  avoid  this,  the  client 
should  use  either  of  two  strategies: 

1.  Map  the  window,  call  XSelect  Input  for  exposure  events,  wait  for  the  first  Expose 
event,  and  repaint  each  window  explicitly. 

2.  Call  XSelect  Input  for  exposure  events,  map,  and  process  input  events  normally. 
Exposure  events  are  generated  for  each  window  that  has  appeared  on  the  screen,  and  the 
client's  normal  response  to  an  Expose  event  should  be  to  repaint  the  window. 

The  latter  method  is  preferred  as  it  usually  leads  to  simpler  programs.  If  you  fail  to  wait  for  the 
Expose  event  in  the  first  method,  it  can  cause  incorrect  behavior  with  certain  window  manag 
ers  that  intercept  the  request. 

Errors 

BadWindow 

Related  Commands 

XMapRaised,  XMapSubwindows,  XUnmapSubwindows,  XUnmapWindow. 


Xlib  Reference  Manual  3 1 7 


XMaskEvent  \ X|lb  _  |nput  Hand||ng_ 

Name 

XMaskEvent  —  remove  the  next  event  that  matches  mask. 

Synopsis 

XMaskEvent  ( display,  event_mask,  rep) 
Display  *display; 
long  event_mask; 
XEvent  *rep;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

even t_mask     Specifies  the  event  mask.   See  XSelect Input  for  a  complete  list  of  the 
event  mask  symbols  that  can  be  ORed  together. 

rep  Returns  the  event  removed  from  the  input  queue. 

Description 

XMaskEvent  removes  the  next  event  in  the  queue  which  matches  the  passed  mask.  The  event 
is  copied  into  an  XEvent  supplied  by  the  caller.  Other  events  in  the  queue  are  not  discarded. 
If  no  such  event  has  been  queued,  XMaskEvent  flushes  the  request  buffer  and  waits  until  one 
is  received.  Use  XCheckMaskEvent  if  you  do  not  wish  to  wait. 

XMaskEvent  never  returns  MappingNotify,  SelectionClear,  SelectionNotify, 
or  SelectionRequest  events.  When  you  specify  ExposureMask  it  will  return 
GraphicsExpose  or  NoExpose  events  if  those  occur. 

Related  Commands 

QLength,  XAllowEvents, XChecklf Event,  XCheckMaskEvent, XCheckTyped- 
Event,  XCheckTypedWindowEvent, XCheckWindowEvent,  XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XNextEvent,  XPeekEvent, 
XPeeklf Event,  XPending,  XPutBackEvent, XSelectlnput, XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 
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Name 

XMatchVisuallnfo  —  obtain  the  visual  information  that  matches  the  desired  depth  and  class. 

Synopsis 

Status  XMatchVisuallnfo ( display,  screen,  depth,  class,  vinfo) 
Display  *display; 
int  screen ; 
int  depth; 
int  class; 
XVisuallnfo  *vinfo;        /*  RETURN  */ 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

screen          Specifies  the  screen. 

depth  Specifies  the  desired  depth  of  the  visual. 

class  Specifies  the  desired  class  of  the  visual,  such  as  Pseudocolor  or  True- 

Color. 

vinfo  Returns  the  matched  visual  information. 

Description 

XMatchVisuallnfo  returns  the  visual  information  for  a  visual  supported  on  the  screen  that 
matches  the  specified  depth  and  class.  Because  multiple  visuals  that  match  the  specified 
depth  and  class  may  be  supported,  the  exact  visual  chosen  is  undefined. 

If  a  visual  is  found,  this  function  returns  a  nonzero  value  and  the  information  on  the  visual  is 
returned  to  vinfo.  If  a  visual  is  not  found,  it  returns  zero. 

For  more  information  on  visuals,  see  Volume  One,  Chapter  7,  Color. 
Structures 

typedef  struct  { 

Visual  *visual; 

VisuallD  visualid; 

int  screen; 

unsigned  int  depth; 

int  class; 

unsigned  long  red_mask; 

unsigned  long  green_mask; 

unsigned  long  blue_mask; 

int  colormap_size; 

int  bits_per_rgb; 
}  XVisuallnfo; 

Related  Commands 

Default Visual, XGetVisuallnf o. 
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XMOVeReSizeWindOW  .  .xpb-«nda.  Manipulation- 

Name 

XMoveResizeWindow  —  change  the  size  and  position  of  a  window. 

Synopsis 

XMoveResizeWindow ( display,  w,  x,  y,  width,  height) 
Display  *display; 
Window  w; 
int  x,  y; 
unsigned  int  width,  height; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  ID  of  the  window  to  be  reconfigured. 

x  Specify  the  new  x  and  y  coordinates  of  the  upper-left  pixel  of  the  window's  bor- 

y  der,  relative  to  the  window's  parent. 

width  Specify  the  new  width  and  height  in  pixels.  These  arguments  define  the  interior 

height  size  of  the  window. 

Description 

XMoveResizeWindow  moves  or  resizes  a  window  or  both.  XMoveResizeWindow  does 
not  raise  the  window.  Resizing  a  mapped  window  may  lose  its  contents  and  generate  an 
Expose  event  on  that  window  depending  on  the  bit_gravity  attribute.  Configuring  a  win 
dow  may  generate  exposure  events  on  windows  that  the  window  formerly  obscured,  depending 
on  the  new  size  and  location  parameters. 

If  the  override_redirect  attribute  of  the  window  is  False  (see  Volume  One,  Chapter  4, 
Window  Attributes)  and  the  window  manager  has  selected  SubstructureRedirectMasJc 
on  the  parent,  then  a  Conf  igureRequest  event  is  sent  to  the  window  manager,  and  no  fur 
ther  processing  is  performed. 

If  the  client  has  selected  StructureNotifyMask  on  the  window,  then  a  Conf igure- 
Notify  event  is  generated  after  the  move  and  resize  takes  place,  and  the  event  will  contain 
the  final  position  and  size  of  the  window. 

Errors 

BadValue 
BadWindow 

Related  Commands 

XCirculateSubwindows, XCirculateSubwindowsDown,  XCirculate- 
SubwindowsUp,  XConf  igureWindow,  XLowerWindow,  XMoveWindow,  XQuery- 
Tree,  XRaiseWindow,  XReparentWindow,  XResizeWindow,  XRestackWindows. 
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Name 

XMoveWindow  —  move  a  window. 

Synopsis 

XMoveWindow (display,  w,  x,  y) 
Display  * display; 
Window  w; 
int  x,  y; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  to  be  moved. 

x  Specify  the  new  x  and  y  coordinates  of  the  upper-left  pixel  of  the  window's  bor- 

y  der  (or  of  the  window  itself,  if  it  has  no  border),  relative  to  the  window's  parent. 

Description 

XMoveWindow  changes  the  position  of  the  origin  of  the  specified  window  relative  to  its  par 
ent.  XMoveWindow  does  not  change  the  mapping  state,  size,  or  stacking  order  of  the  window, 
nor  does  it  raise  the  window.  Moving  a  mapped  window  will  lose  its  contents  if: 

Its  background_pixmap  attribute  is  ParentRelative. 

The  window  is  obscured  by  nonchildren  and  no  backing  store  exists. 

If  the  contents  are  lost,  exposure  events  will  be  generated  for  the  window  and  any  mapped 
subwindows.  Moving  a  mapped  window  will  generate  exposure  events  on  any  formerly 
obscured  windows. 

If  the  override_redirect  attribute  of  the  window  is  False  (see  Volume  One,  Chapter  4, 
Window  Attributes)  and  the  window  manager  has  selected  SubstructureRedirectMask 
on  the  parent,  then  a  Conf  igureRequest  event  is  sent  to  the  window  manager,  and  no  fur 
ther  processing  is  performed. 

If  the  client  has  selected  StructureNotifyMask  on  the  window,  then  a  Conf  igure- 
Notif  y  event  is  generated  after  the  move  takes  place,  and  the  event  will  contain  the  final  posi 
tion  of  the  window. 

Errors 

BadWindow 

Related  Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp,  XConf  igureWindow,  XLowerWindow,  XMoveResizeWindow, 
XQueryTree,  XRaiseWindow,  XReparentWindow,  XResizeWindow,  XRestack- 
Windows. 
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XNewModifiermap  \ m  _  Keyboard_ 

Name 

XNewModifiermap  —  create  a  keyboard  modifier  mapping  structure. 

Synopsis 

XModif ierKeymap  * XNewModifiermap (max_keys_per_mod) 
int  max_keys_per_mod; 

Arguments 

max_keys_jper_mod 

Specifies  the  maximum  number  of  keycodes  assigned  to  any  of  the  modifiers  in  the 
map. 

Description 

XNewModifiermap  returns  a  XModif  ierKeymap  structure  and  allocates  the  needed  space. 
This  function  is  used  when  more  than  one  XModif  ierKeymap  structure  is  needed. 
max_keys_per_mod  depends  on  the  server  and  should  be  gotten  from  the  XModif  ier 
Keymap  returned  by  XGetModif  ierMapping. 

For  more  information  on  keyboard  preferences,  see  Volume  One,  Chapter  9,  The  Keyboard  and 
Pointer. 

Structures 

typedef  struct  { 

int  max_keypermod;      /*  server's  max  number  of  keys  per  modifier  */ 
KeyCode  *modif iermap;   /*  An  8  by  max_keypermod  array 
*  of  the  modifiers  */ 

}  XModifierKeymap; 

Related  Commands 

XChangeKeyboardMapping,  XDeleteModifiermapEntry,  XFreeModif  iermap, 
XGetKeyboardMapping, XGetModif ierMapping,  XInsertModif iermapEntry, 
XKeycodeToKeysym,  XKeysymToKeycode,  XKeysymToString,  XLookupKeysym, 
XLookupString,  XQueryKeymap,  XRebindKeysym,  XRef  reshKeyboardMapping, 
XSetModif ierMapping,  XStringToKeysym. 
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-Xllb  -  input  HandHng /  XNeXtEvent 

Name 

XNextEvent  —  get  the  next  event  of  any  type  or  window. 

Synopsis 

XNextEvent  ( display,  report) 
Display  *  display; 
XEvent  *  report;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

report  Returns  the  event  removed  from  the  event  queue. 

Description 

XNextEvent  removes  an  event  from  the  head  of  the  event  queue  and  copies  it  into  an 
XEvent  structure  supplied  by  the  caller.  If  the  event  queue  is  empty,  XNextEvent  flushes 
the  request  buffer  and  waits  (blocks)  until  an  event  is  received.  Use  XGheckMaskEvent  or 
XChecklf  Event  if  you  do  not  want  to  wait. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength,  XAllowEvents, XChecklf Event,  XCheckMaskEvent, XCheckTyped- 
Event,  XCheckTypedWindowEvent, XCheckWindowEvent,  XEventsQueued, 
XGetlnputFocus,  XGetMotionEvents,  Xlf  Event,  XMaskEvent,  XPeekEvent, 
XPeeklf Event,  XPending, XPutBackEvent, XSelectlnput, XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 
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Name 

XNoOp  —  send  a  NoOp  to  exercise  connection  with  the  server. 

Synopsis 

XNoOp  (display) 

Display   * display; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

Description 

XNoOp  sends  a  NoOperation  request  to  the  X  server,  thereby  exercising  the  connection. 
This  request  can  be  used  to  measure  the  response  time  of  the  network  connection.  XNoOp  does 
not  flush  the  request  buffer. 

Related  Commands 

Def aultScreen, XCloseDisplay,  XFree,  XOpenDisplay. 
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J  XOffsetReglon 


Name 

XOffsetRegion  —  change  offset  of  a  region. 

Synopsis 

XOffsetRegion  (r,  dx ,  dy) 
Region  r; 
int  dx  f  dy ; 

Arguments 

r  Specifies  the  region. 

dx  Specify  the  amount  to  move  the  specified  region  relative  to  the  origin  of  all 

dy  regions. 


Description 

XOffsetRegion  changes  the  offset  of  the  region  the  specified  amounts  in  the  x  and  y  direc 
tions. 

Regions  are  located  using  an  offset  from  a  point  (the  region  origin)  which  is  common  to  all 
regions.  It  is  up  to  the  application  to  interpret  the  location  of  the  region  relative  to  a  drawable. 
If  the  region  is  to  be  used  as  a  clipjmask  by  calling  XSetRegion,  the  upper-left  corner  of 
the  region  relative  to  the  drawable  used  in  the  graphics  request  will  be  at  (xof  fset  + 
clip_x_origin,  yof  f  set  +  clip_y_origin) ,  where  xof  fset  and  yof  f  set  are 
the  offset  of  the  region  and  clip_x_origin  and  clip_y_origin  are  components  of  the 
GC  used  in  the  graphics  request. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion, XDestroyRegion, XEmptyRegion,  XEqualRegion, 
XIntersectRegion, XPointlnRegion, XPolygonRegion, XRectlnRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion,  XUnionRectWithRegion, 
XUnionRegion,  XXorRegion. 
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XOpenDisplay 


X 


Xlib-HouseKeeping  — 


Name 

XOpenDisplay  —  connect  a  client  program  to  an  X  server. 

Synopsis 

Display   *XOpenDisplay ( display_name) 
char    *display_name; 

Arguments 

di spl ay_name 

Specifies  the  display  name,  which  determines  the  server  to  connect  to  and  the 
communications  domain  to  be  used.  See  Description  below. 

Description 

The  XOpenDisplay  routine  connects  the  client  to  the  server  controlling  the  hardware  display 
through  TCP,  or  UNIX  or  DECnet  streams. 

If  display_name  is  NULL,  the  value  defaults  to  the  contents  of  the  DISPLAY  environment 
variable  on  UNIX-based  systems.  On  non-UNIX-based  systems,  see  that  operating  system's 
Xlib  manual  for  the  default  display_name.  The  display_name  or  DISPLAY  environment 
variable  is  a  string  that  has  the  format  hostname:  server  or  host 
name:  server. screen.  For  example,  frog :  0  . 2  would  specify  screen  2  of  server  0  on  the 
machine  frog. 

hostname  Specifies  the  name  of  the  host  machine  on  which  the  display  is  physically  con 
nected.  You  follow  the  hostname  with  either  a  single  colon  (:)  or  a  double  colon 
(::),  which  determines  the  communications  domain  to  use.  Any  or  all  of  the 
communication  protocols  can  be  used  simultaneously  on  a  server  built  to  sup 
port  them  (but  only  one  per  client). 

If  hostname  is  a  host  machine  name  and  a  single  colon  (:)  separates  the 
hostname  and  display  number,  XOpenDisplay  connects  the  hardware 
display  to  TCP  streams.  In  Release  4  and  later,  the  string  "unix"  is  no 
longer  required  and  the  string  ":o"  connects  the  local  server. 

If  hostname  is  "unix"  and  a  single  colon  (:)  separates  it  from  the  display 
number,  XOpenDisplay  connects  the  hardware  display  to  UNIX  domain 
IPC  streams.  In  Release  4,  the  string  "unix"  should  be  omitted. 

•  If  hostname  is  a  host  machine  name  and  a  double  colon  (::)  separates 
the  hostname  and  display  number,  XOpenDisplay  connects  with  the 
server  using  DECnet  streams.  To  use  DECnet,  however,  you  must  build 
all  software  for  DECnet.  A  single  X  server  can  accept  both  TCP  and 
DECnet  connections  if  it  has  been  built  for  DECnet. 

server  Specifies  the  number  of  the  server  on  its  host  machine.  This  display  number 
may  be  followed  by  a  period  (.).  A  single  CPU  can  have  more  than  one  display; 
the  displays  are  numbered  starting  from  0. 
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screen  Specifies  the  number  of  the  default  screen  on  server.  Multiple  screens  can  be 
connected  to  (controlled  by)  a  single  X  server,  but  they  are  used  as  a  single  dis 
play  by  a  single  user,  screen  merely  sets  an  internal  variable  that  is  returned 
by  the  Def  aultScreen  macro.  If  screen  is  omitted,  it  defaults  to  0. 

If  successful,  XOpenDisplay  returns  a  pointer  to  a  Display.  This  structure  provides  many 
of  the  specifications  of  the  server  and  its  screens.  If  XOpenDisplay  does  not  succeed,  it 
returns  a  NULL. 

After  a  successful  call  to  XOpenDisplay,  all  of  the  screens  on  the  server  may  be  used  by  the 
application.  The  screen  number  specified  in  the  display_name  argument  serves  only  to 
specify  the  value  that  will  be  returned  by  the  Def  aultScreen  macro.  After  opening  the  dis 
play,  you  can  use  the  ScreenCount  macro  to  determine  how  many  screens  are  available. 
Then  you  can  reference  each  screen  with  integer  values  between  0  and  the  value  returned  by 
(ScreenCount  -1). 

For  more  information,  see  Volume  One,  Chapter  2,  X  Concepts,  and  Chapter  3,  Basic  Window 
Program. 

Related  Commands 

Def  aultScreen,  XCloseDisplay,  XFree,  XNoOp. 
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XParseColor  „ x,,b-co,orce,,s- 

Name 

XParseColor  —  look  up  RGB  values  from  ASCII  color  name  or  translate  hexadecimal  value. 

Synopsis 

Status  XParseColor ( display,  colormap,  spec,  rgb_db_def) 
Display  ^display; 
Colormap  colormap; 
char  *spec; 
XColor  *rgb_db_def;        /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

colormap  Specifies  a  colormap.  This  argument  is  required  but  is  not  used.  The  same 
code  is  used  to  process  XParseColor  and  XLookupColor,  but  only 
XLookupColor  returns  the  closest  values  physically  possible  on  the  screen 
specified  by  colormap. 

spec  Specifies  the  color  specification,  either  as  a  color  name  or  as  hexadecimal 

coded  in  ASCII  (see  below).  Upper  or  lower  case  does  not  matter.  The  string 
must  be  null-terminated,  and  should  be  in  ISO  LATIN- 1  encoding,  which 
means  that  the  first  128  character  codes  are  ASCII,  and  the  second  128  char 
acter  codes  are  for  special  characters  needed  in  western  languages  other  than 
English. 

rgb_db_def  Returns  the  RGB  values  corresponding  to  the  specified  color  name  or  hexade 
cimal  specification,  and  sets  its  DoRed,  DoGreen  and  DoBlue  flags. 

Description 

XParseColor  returns  the  RGB  values  corresponding  to  the  English  color  name  or  hexade 
cimal  values  specified,  by  looking  up  the  color  name  in  the  color  database,  or  translating  the 
hexadecimal  code  into  separate  RGB  values.  It  takes  a  string  specification  of  a  color,  typically 
from  a  command  line  or  XGet Default  option,  and  returns  the  corresponding  red,  green,  and 
blue  values,  suitable  for  a  subsequent  call  to  XAllocColor  or  XStoreColor.  spec  can  be 
given  either  as  an  English  color  name  (as  in  XAllocNamedColor)  or  as  an  initial  sharp  sign 
character  followed  by  a  hexadecimal  specification  in  one  of  the  following  formats: 

#RGB  (one  character  per  color) 

#RRGGBB  (two  characters  per  color) 

#RRRGGGBBB  (three  characters  per  color) 

#RRRRGGGGBBBB  (four  characters  per  color) 

where  R,  G,  and  B  represent  single  hexadecimal  digits  (upper  or  lower  case). 

The  hexadecimal  strings  must  be  null-terminated  so  that  XParseColor  knows  when  it  has 
reached  the  end.  When  fewer  than  16  bits  each  are  specified,  they  represent  the  most  signifi 
cant  bits  of  the  value.  For  example,  #  3  a  7  is  the  same  as#3000a0007000. 
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This  routine  will  fail  and  return  aStatusof  zero  if  the  initial  character  is  a  sharp  sign  but  the 
string  otherwise  fails  to  fit  one  of  the  above  formats,  or  if  the  initial  character  is  not  a  sharp  sign 
and  the  named  color  does  not  exist  in  the  server's  database. 

Status  is  zero  on  failure,  nonzero  on  success. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 

Structures 

typedef  struct  { 

unsigned  long  pixel; 

unsigned  short  red,  green,  blue; 

char  flags;  /*  DoRed,  DoGreen,  DoBlue  */ 

char  pad; 
}  XColor; 

Errors 

BadColormap 

Related  Commands 

BlackPixel, WhitePixel, XAllocColor,  XAllocColorCells,  XAllocColor- 
Planes,  XAllocNamedColor, XFreeColors,  XLookupColor,  XQueryColor, 
XQueryColors, XStoreColor, XStoreColors,  XStoreNamedColor. 
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XParseGeometry  . Vll 

v Xlib  -  Standard  Geometry— 

Name 

XParseGeometry  —  generate  position  and  size  from  standard  window  geometry  string. 

Synopsis 

int  XParseGeometry (parsestring,  x,  y,  width,  height) 
char  *parsestring; 

int  *x,  *y;  /*  RETURN  */ 

unsigned  int  * width,  *height;       /*  RETURN  */ 

Arguments 

parsestring        Specifies  the  string  you  want  to  parse. 

x  Return  the  x  and  y  coordinates  (offsets)  from  the  string. 

y 

wi  dth  Return  the  width  and  height  in  pixels  from  the  string. 

height 

Description 

By  convention,  X  applications  provide  a  geometry  command  line  option  to  indicate  window 
size  and  placement.  XParseGeometry  makes  it  easy  to  conform  to  this  standard  because  it 
allows  you  to  parse  the  standard  window  geometry  string.  Specifically,  this  function  lets  you 
parse  strings  of  the  form: 

=  < wi dth>x<height>  {  +- }  <xoffset>  { '+- }  <yoffset> 

The  items  in  this  string  map  into  the  arguments  associated  with  this  function.  (Items  enclosed 
in  o'are  integers  and  items  enclosed  in  { }  are  a  set  from  which  one  item  is  allowed.  Note  that 
the  brackets  should  not  appear  in  the  actual  string.) 

XParseGeometry  returns  a  bitmask  that  indicates  which  of  the  four  values  (width, 
height,  xoffset,  and  yoffset)  were  actually  found  in  the  string,  and  whether  the  x  and  y 
values  are  negative.  The  bits  are  represented  by  these  constants:  XValue,  YValue,  width- 
Value,  Height  Value,  XNegative,  and  YNegative,  and  are  defined  in  <Xll/Xutil.h>. 
For  each  value  found,  the  corresponding  argument  is  updated  and  the  corresponding  bitmask 
element  set;  for  each  value  not  found,  the  argument  is  left  unchanged,  and  the  bitmask  element 
is  not  set. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 
Related  Commands 

XGeometry, XTranslateCoordinates, XWMGeometry. 
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-X.ib  -  input  Handling ' 

Name 

XPeekEvent  —  get  an  event  without  removing  it  from  the  queue. 

Synopsis 

XPeekEvent ( display,  report) 
Display  *  display; 
XEvent  *  report;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

report  Returns  the  event  peeked  from  the  input  queue. 

Description 

XPeekEvent  peeks  at  an  input  event  from  the  head  of  the  event  queue  and  copies  it  into  an 
XEvent  supplied  by  the  caller,  without  removing  it  from  the  input  queue.  If  the  queue  is 
empty,  XPeekEvent  flushes  the  request  buffer  and  waits  (blocks)  until  an  event  is  received. 
If  you  do  not  want  to  wait,  use  the  QLength  macro  to  determine  if  there  are  any  events  to  peek 
at,  or  use  XPeeklf  Event.  XEventsQueued  can  perform  the  function  of  either  QLength 
or  XPending  and  more. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event,  XCheckTypedWindowEvent,  XCheckWindowEvent,  XEventsQueued, 
XGetlnputFocus,  XGetMotionEvents,  Xlf Event,  XMaskEvent,  XNextEvent, 
XPeeklf Event, XPending,  XPutBackEvent,  XSelectlnput,  XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 
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XPeeklfEvent  \ X|lb  _  |nput  Hand|lng_ 

Name 

XPeeklfEvent  —  get  an  event  matched  by  predicate  procedure  without  removing  it  from  the 
queue. 

Synopsis 

XPeeklfEvent ( display ,  event,  predicate,  args) 
Display  *display; 

XEvent  *event;  /*  RETURN  */ 

Bool  (^predicate)  () ; 
char  *args; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

event  Returns  the  matched  event. 

predicate       Specifies  the  procedure  to  be  called  to  determine  if  each  event  that  arrives  in 
the  queue  is  the  desired  one. 

args  Specifies  the  user- specified  arguments  that  will  be  passed  to  the  predicate 

procedure. 

Description 

XPeeklfEvent  returns  an  event  only  when  the  specified  predicate  procedure  returns  True 
for  the  event.  The  event  is  copied  into  event  but  not  removed  from  the  queue.  The  specified 
predicate  is  called  each  time  an  event  is  added  to  the  queue,  with  the  arguments  display, 
event,  and  arg. 

XPeeklfEvent  flushes  the  request  buffer  if  no  matching  events  could  be  found  on  the  queue, 
and  then  waits  for  the  next  matching  event. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event,  XCheckTypedWindowEvent, XCheckWindowEvent,  XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent,  XNextEvent, 
XPeekEvent, XPending,  XPutBackEvent, XSelectlnput, XSendEvent, XSet- 
InputFocus, XSynchronize, XWindowEvent. 


332  Xlib  Reference  Manual 


—  Xlib -Input  Handling- 


J  XPending 


Name 

XPending  —  flush  the  request  buffer  and  return  the  number  of  pending  input  events. 

Synopsis 

int   XPending  ( display) 
Display    *display; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

Description 

XPending  returns  the  number  of  input  events  that  have  been  received  by  Xlib  from  the  server, 
but  not  yet  removed  from  the  queue.  If  there  are  no  events  on  the  queue,  XPending  flushes 
the  request  buffer,  and  returns  the  number  of  events  transferred  to  the  input  queue  as  a  result  of 
the  flush. 

The  QLength  macro  returns  the  number  of  events  on  the  queue,  but  without  flushing  the 
request  buffer  first. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event,  XCheckTypedWindowEvent, XCheckWindowEvent,  XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent,  XNextEvent, 
XPeekEvent,  XPeeklf Event, XPutBackEvent, XSelectlnput, XSendEvent, 
XSetlnputFocus, XSynchronize, XWindowEvent. 
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Xpermalloc  \ Vll 

v Xlib  -  Resource  Manager— 

Name 

Xpermalloc  —  allocate  memory  never  to  be  freed. 

Synopsis 

char  *Xpermalloc ( size) 
unsigned  int  size; 

Arguments 

si  ze  Specifies  the  size  in  bytes  of  the  space  to  be  allocated.  This  specification  is 

rounded  to  the  nearest  4-byte  boundary. 

Description 

Xpermalloc  allocates  some  memory  that  will  not  be  freed  until  the  process  exits.  Xperm 
alloc  is  used  by  some  toolkits  for  permanently  allocated  storage  and  allows  some  perfor 
mance  and  space  savings  over  the  completely  general  memory  allocator. 
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—  Xlib  -Regions- 


J  XPointlnRegion 


Name 

XPointlnRegion  —  determine  if  a  point  is  inside  a  region. 

Synopsis 

Bool  XPointlnRegion (r,  x,  y) 
Region  r; 
int  x,  y; 

Arguments 

r  Specifies  the  region. 

x  Specify  the  x  and  y  coordinates  of  the  point  relative  to  the  region's  origin. 

y 

Description 

XPointlnRegion  returns  True  if  the  point  x,  y  is  contained  in  the  region  r.   A  point 
exactly  on  the  boundary  of  the  region  is  considered  inside  the  region. 

Regions  are  located  using  an  offset  from  a  point  (the  region  origin)  which  is  common  to  all 
regions.  It  is  up  to  the  application  to  interpret  the  location  of  the  region  relative  to  a  drawable. 

For  more  information  on  regions,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPolygonRegion, XRectlnRegion, XSet- 
Region,  XShrinkRegion, XSubtractRegion,  XUnionRectWithRegion, XUnion- 
Region, XXorRegion. 
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XPolygonRegion  \. 


xi|b 


Name 

XPolygonRegion  —  generate  a  region  from  points. 

Synopsis 

Region  XPolygonRegion  (points  ,  n,  fill_rule) 
XPoint  points  []  ; 
int  n; 
int  fill_rule; 

Arguments 

points  Specifies  a  pointer  to  an  array  of  points. 

n  Specifies  the  number  of  points  in  the  polygon. 

fill_rule  Specifies  whether  areas  overlapping  an  odd  number  of  times  should  be  part  of 
the  region  (windingRule)  or  not  part  of  the  region  (EvenOddRule).  See 
Volume  One,  Chapter  5,  The  Graphics  Context,  for  a  description  of  the  fill 
rule. 

Description 

XPolygonRegion  creates  a  region  defined  by  connecting  the  specified  points,  and  returns  a 
pointer  to  be  used  to  refer  to  the  region. 

Regions  are  located  relative  to  a  point  (the  region  origin)  which  is  common  to  all  regions.  In 
XPolygonRegion,  the  coordinates  specified  in  points  are  relative  to  the  region  origin.  By 
specifying  all  points  relative  to  the  drawable  in  which  they  will  be  used,  the  region  origin  can 
be  coincident  with  the  drawable  origin.  It  is  up  to  the  application  whether  to  interpret  the  loca 
tion  of  the  region  relative  to  a  drawable  or  not. 

If  the  region  is  to  be  used  as  a  clip_mask  by  calling  XSetRegion,  the  upper-left  corner  of 
the  region  relative  to  the  drawable  used  in  the  graphics  request  will  be  at  (xof  f  set  + 
clip_x_origin,  yof  f  set  +  clip_y_origin)  ,  where  xof  f  set  and  yof  f  set  are 
the  offset  of  the  region  (if  any)  and  clip_x_origin  and  clip_y_origin  are  elements  of 
the  GC  used  in  the  graphics  request.  The  fill_rule  can  be  either  of  these  values: 

•  EvenOddRule  Areas  overlapping  an  odd  number  of  times  are  not  part  of  the  region. 

•  windingRule  Overlapping  areas  are  always  filled. 

For  more  information  on  structures,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion,  XDestroyRegion,  XEmptyRegion,  XEqualRegion, 
XIntersectRegion,  XOf  f  setRegion,  XPointlnRegion,  XRectlnRegion,  XSet 
Region,  XShrinkRegion,  XSubtractRegion,  XUnionRectWithRegion,  XUnion- 
Region,  XXorRegion. 
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-XMb  -  ,npu,  Hand,ing 


Name 

XPutBackEvent  —  push  an  event  back  on  the  input  queue. 

Synopsis 

XPutBackEvent  (display  ,  event) 
Display  ^display; 
XEvent  *  event; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi  splay. 

even  t  Specifies  a  pointer  to  the  event  to  be  requeued. 

Description 

XPutBackEvent  pushes  an  event  back  onto  the  head  of  the  current  display's  input  queue  (so 
that  it  would  become  the  one  returned  by  the  next  XNextEvent  call).  This  can  be  useful  if 
you  have  read  an  event  and  then  decide  that  you'd  rather  deal  with  it  later.  There  is  no  limit  to 
how  many  times  you  can  call  XPutBackEvent  in  succession. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 
Related  Commands 

QLength,  XAllowEvents,  XChecklf  Event,  XCheckMaskEvent,  XCheckTyped- 
Event,  XCheckTypedWindowEvent,  XCheckWindowEvent,  XEventsQueued, 
XGetlnputFocus,  XGetMotionEvents,  Xlf  Event,  XMaskEvent,  XNextEvent, 
XPeekEvent,  XPeeklf  Event,  XPending,  XSelectlnput,  XSendEvent,  XSet- 
InputFocus,  XSynchronize,  XWindowEvent. 
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XPutlma9e  x,,b  - 

Name 

XPutlmage  —  draw  an  image  on  a  window  or  pixmap. 

Synopsis 

XPutlmage ( display,    drawable,    gc ,    image,    src_x,    src_y, 

dst_x,    dst_y,    width,    height) 
Display    ^display; 
Drawable   drawable; 
GC   gc ; 

Xlmage    * image; 
int    src_x,    src_y; 
int    dst_x,    dst_y ; 
unsigned   int    width,    height; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

drawable          Specifies  the  drawable. 

gc  Specifies  the  graphics  context. 

image  Specifies  the  image  you  want  combined  with  the  rectangle. 

src_x  Specify  the  coordinates  of  the  upper-left  corner  of  the  rectangle  to  be  copied, 

src_y  relative  to  the  origin  of  the  image. 

dst_x  Specify  the  x  and  y  coordinates,  relative  to  the  origin  of  the  drawable,  where 

dst_y  the  upper-left  corner  of  the  copied  rectangle  will  be  placed. 

wi  dth  Specify  the  width  and  height  in  pixels  of  the  rectangular  area  to  be  copied. 

height 

Description 

XPutlmage  draws  a  section  of  an  image  on  a  rectangle  in  a  window  or  pixmap.  The  section 
of  the  image  is  defined  by  src_x,  src_y,  width  and  height. 

There  is  no  limit  to  the  size  of  image  that  can  be  sent  to  the  server  using  XPutlmage.  XPut 
lmage  automatically  decomposes  the  request  to  make  sure  that  the  maximum  request  size  of 
the  server  is  not  exceeded. 

XPutlmage  uses  these  graphics  context  components:  function,  plane_mask,  subwin- 
dow_mode,  clip_x_origin,  clip_y_origin,  and  clip_mask.  This  function  also 
uses  these  graphics  context  mode-dependent  components:  foreground  and  background. 

If  an  XYBitmap  format  image  is  used,  then  the  depth  of  drawable  must  be  1,  otherwise  a 
BadMatch  error  is  generated.  The  foreground  pixel  in  gc  defines  the  source  for  bits  set  to 
one  in  the  image,  and  the  background  pixel  defines  the  source  for  the  bits  set  to  zero. 

For  XYPixmap  and  ZPixmap  format  images,  the  depth  of  the  image  must  match  the  depth  of 

drawable. 
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Xlib  -  Images  (continued)  XPutlmage 

Structures 

typedef  struct  _XImage  { 

int  width,  height;      /*  size  of  image  */ 

int  xoffset;  /*  number  of  pixels  offset  in  x  direction  */ 

int  format;  /*  XYBitmap,  XYPixmap,  ZPixmap  */ 

char  *data;  /*  pointer  to  image  data  */ 

int  byte_order;        /*  data  byte  order,  LSBFirst,  MSBFirst  */ 

int  bitmap_unit;       /*  quant,  of  scan  line  8,  16,  32  */ 

int  bitmap_bit_order;   /*  LSBFirst,  MSBFirst  */ 

int  bitmap_pad;        /*  8,  16,  32  either  XY  or  ZPixmap  */ 

int  depth;  /*  depth  of  image  */ 

int  bytes_per_line;     /*  accelerator  to  next  line  */ 

int  bits_per_pixel;     /*  bits  per  pixel  (ZPixmap)  */ 

char  *obdata;          /*  hook  for  the  object  routines  to  hang  on  */ 

struct  funcs  {          /*  image  manipulation  routines  */ 

struct  _XImage  *  (*create_image) (); 

int  { *destroy_image) (); 

unsigned  long  ( *get_pixel) () ; 

int  (*put_pixel) () ; 

struct  __XImage  *  (*sub_image)  (); 

int  (*add_pixel) () ; 
}  f; 
}  X Image; 

Errors 

BadDrawable 

BadGC 

BadMatch          See  Description  above. 

BadValue 

Related  Commands 

ImageByteOrder,  XAddPixel,  XCreatelmage,  XDestroy Image,  XGet  Image, 
XGetPixel, XGetSublmage, XPutPixel, XSublmage. 
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XPutPixel  "\ v, 

v Xlib  -  Images- 
Name 

XPutPixel  —  set  a  pixel  value  in  an  image. 

Synopsis 

int  XPutPixel (ximage f  xf  y,  pixel) 
Xlmage  * ximage; 
int  x; 
int  y; 
unsigned  long  pixel; 

Arguments 

ximage  Specifies  a  pointer  to  the  image  to  be  modified. 

x  Specify  the  x  and  y  coordinates  of  the  pixel  to  be  set,  relative  to  the  origin  of 

y  the  image. 

pixel  Specifies  the  new  pixel  value. 

Description 

XPutPixel  overwrites  the  pixel  in  the  named  image  with  the  specified  pixel  value.  The  x 
and  y  coordinates  are  relative  to  the  origin  of  the  image.  The  input  pixel  value  must  be  in  same 
bit-  and  byte-order  as  the  machine  in  which  the  client  is  running  (that  is,  the  Least  Significant 
Byte  (LSB)  of  the  long  is  the  LSB  of  the  pixel).  The  x  and  y  coordinates  must  be  contained  in 
the  image. 

Structures 

typedef  struct   Ximage  { 

int  width,  height;  /*  size  of  image  */ 

int  xoffset;  /*  number  of  pixels  offset  in  x  direction  */ 

int  format;  /*  XYBitmap,  XYPixmap,  ZPixmap  */ 

char  *data;  /*  pointer  to  image  data  */ 

int  byte_order;  /*  data  byte  order,  LSBFirst,  MSBFirst  */ 

int  bitmap_unit;  /*  quant,  of  scan  line  8,  16,  32  */ 

int  bitmap_bit_order;  /*  LSBFirst,  MSBFirst  */ 

int  bitmap_pad;  /*  8,  16,  32  either  XY  or  ZPixmap  */ 

int  depth;  /*  depth  of  image  */ 

int  bytes_per_line;  /*  accelerator  to  next  line  */ 

int  bits_per_pixel;  /*  bits  per  pixel  (ZPixmap)  */ 

unsigned  long  red_mask;  /*  bits  in  z  arrangment  */ 

unsigned  long  green_mask; 

unsigned  long  blue_mask; 

char  *obdata;  /*  hook  for  the  object  routines  to  hang  on  */ 

struct  funcs  {  /*  image  manipulation  routines  */ 

struct  _XImage  * (*create_image)  ( )  ; 

int  (*destroy_image) (); 

unsigned  long  (*get_pixel)( ) ; 

int  (*put_pixel)  ()  ; 

struct   Ximage  *  (*sub  image)  (); 

int  (*add_pixel)  ()  ; 
}  f; 
}  Ximage; 
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Xlib- Images  (continued)  XPutPixel 

Related  Commands 

ImageByteOrder,  XAddPixel,  XCreate Image,  XDestroy Image,  XGetlmage, 
XGetPixel,  XGetSublmage, XPutlmage, XSublmage. 
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XQueryBestCursor  v^ 


-Xlib- Cursors- 


Name 

XQueryBestCursor  —  get  the  closest  supported  cursor  sizes. 

Synopsis 

Status  XQueryBestCursor  (display,  draw-able,  width,  height, 

rwidth,  rheight) 
Display  * display ; 
Drawable  drawable; 
unsigned  int  width,  height; 
unsigned  int  * rwidth,  * rheight /  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

draw-able          Specifies  a  drawable  that  indicates  which  screen  the  cursor  is  to  be  used  on. 
The  best  cursor  may  be  different  on  different  screens. 

width  Specify  the  preferred  width  and  height,  in  pixels. 

height 

rwidth  Returns  the  closest  supported  cursor  dimensions,  in  pixels,  on  the  display 

rh  ei  gh  t  hardware. 

Description 

XQueryBestCursor  returns  the  closest  cursor  dimensions  actually  supported  by  the  display 
hardware  to  the  dimensions  you  specify. 

Call  this  function  if  you  wish  to  use  a  cursor  size  other  than  16  by  16.  XQueryBestCursor 
provides  a  way  to  find  out  what  size  cursors  are  actually  possible  on  the  display.  Applications 
should  be  prepared  to  use  smaller  cursors  on  displays  which  cannot  support  large  ones. 

XQueryBestCursor  returns  nonzero  if  the  call  succeeded  in  getting  a  supported  size  (which 
may  be  the  same  or  different  from  the  specified  size),  or  zero  if  the  call  failed. 

Errors 

BadDrawable 

Related  Commands 

XCreateFontCursor,  XCreateGlyphCursor, XCreatePixmapCursor, XDef ine- 
Cursor, XFreeCursor, XQueryBestSize, XRecolorCursor, XUndef ineCursor. 
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—  Xlib  -  Pixmaps  and  Tiles - 


J  XQueryBestSize 


Name 

XQueryBestSize  —  obtain  the  "best"  supported  cursor,  tile,  or  stipple  size. 

Synopsis 

Status  XQueryBestSize (display,  class,  drawable,  width, 

height,  rwidth,  rheight) 
Display  * display ; 
int  class; 
Drawable  drawable; 
unsigned  int  width,  height; 
unsigned  int  * rwidth,  * rheight;  /*  RETURN  */ 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

class  Specifies  the  class  that  you  are  interested  in.  Pass  one  of  these  constants: 

TileShape, CursorShape,  or  StippleShape. 

drawable         Specifies  a  drawable  ID  that  tells  the  server  which  screen  you  want  the  best 
size  for. 

width  Specify  the  preferred  width  and  height  in  pixels. 

height 

rwidth  Return  the  closest  supported  width  and  height,  in  pixels,  available  for  the 

rheight  object  on  the  display  hardware. 

Description 

XQueryBestSize  returns  the  "fastest"  or  "closest"  size  to  the  specified  size.  For  class  of 
CursorShape,  this  is  the  closest  size  that  can  be  fully  displayed  on  the  screen.  For  Tile- 
Shape  and  StippleShape,  this  is  the  closest  size  that  can  be  tiled  or  stippled  "fastest." 

For  CursorShape,  the  drawable  indicates  the  desired  screen.  For  TileShape  and 
StippleShape,  the  drawable  indicates  the  screen  and  possibly  the  visual  class  and  depth 
(server-dependent).  An  inputOnly  window  cannot  be  used  as  the  drawable  for  TileShape 
or  StippleShape  (else  a  BadMatch  error  occurs). 

XQueryBestSize  returns  nonzero  if  the  call  succeeded  in  getting  a  supported  size  (may  be 
the  same  or  different  from  the  specified  size),  or  zero  if  the  call  failed. 

Errors 

BadDrawable 

BadMatch    InputOnly  drawable  for  class  TileShape  or  StippleShape. 
BadValue 
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XQueryBeStSize  (continued)  Xlib  -  Pixmaps  and  Tiles 

Related  Commands 

XCreateBitmapFromData, XCreatePixmap,  XCreatePixmapFromBitmapData, 
XFreePixmap,  XQueryBestStipple, XQueryBestTile,  XReadBitmapFile, 
XSetTile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, 
XWriteBitmapFile. 
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— Xlib  -  Pixmaps  and  Tiles - 


J  XQueryBestStipple 


Name 

XQueryBestStipple  —  obtain  the  fastest  supported  stipple  shape. 

Synopsis 

Status  XQueryBestStipple (display,  drawable,  width,  height, 

rwidth,  rheight) 
Display  * display; 
Drawable  drawable; 
unsigned  int  width,  height; 
unsigned  int  *rwidth,  * rheight;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawable         Specifies  a  drawable  that  tells  the  server  which  screen  you  want  the  best  size 
for. 

width  Specify  the  preferred  width  and  height  in  pixels. 

height 

rwidth  Return  the  width  and  height,  in  pixels,  of  the  stipple  best  supported  by  the 

rh ei  gh  t  display  hardware. 

Description 

XQueryBestStipple  returns  the  closest  stipple  size  that  can  be  stippled  fastest.  The  draw- 
able  indicates  the  screen  and  possibly  the  visual  class  and  depth.  An  inputOnly  window 
cannot  be  used  as  the  drawable  (else  a  BadMatch  error  occurs). 

XQueryBestStipple  returns  nonzero  if  the  call  succeeded  in  getting  a  supported  size  (may 
be  the  same  or  different  from  the  specified  size),  or  zero  if  the  call  failed. 

For  more  information  on  stipples,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 

Errors 

BadDrawable 

BadMatch  InputOnly  window. 

Related  Commands 

XCreateBitmapFromData,  XCreatePixmap,  XCreatePixmapFromBitmapData, 
XFreePixmap,  XQueryBestSize, XQueryBestTile, XReadBitmapFile, XSet- 
Tile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap,  XWrite- 
BitmapFile. 
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XQueryBestTile  \ X||b  _  pixmaps  and  T||es_ 

Name 

XQueryBestTile  —  obtain  the  fastest  supported  fill  tile  shape. 

Synopsis 

Status  XQueryBestTile  ( display,  drawable,  width,  height, 

rwidth,  rheight) 
Display  * display; 
Drawable  drawable ; 
unsigned  int  width,  height; 
unsigned  int  * rwidth,  * rheight ;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

drawable         Specifies  a  drawable  that  tells  the  server  which  screen  you  want  the  best  size 
for. 

wi  dth  Specify  the  preferred  width  and  height  in  pixels. 

height 

rwidth  Return  the  width  and  height,  in  pixels,  of  the  tile  best  supported  by  the  dis- 

r height  play  hardware. 

Description 

XQueryBestTile  returns  the  closest  size  that  can  be  tiled  fastest.  The  drawable  indicates 
the  screen  and  possibly  the  visual  class  and  depth.  An  Input  Only  window  cannot  be  used  as 
the  drawable. 

XQueryBestTile  returns  nonzero  if  the  call  succeeded  in  getting  a  supported  size  (may  be 
the  same  or  different  from  the  specified  size),  or  zero  if  the  call  failed. 

For  more  information  on  tiles,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
Errors 

BadDrawable 

BadMatch          InputOnly  drawable  specified. 

Related  Commands 

XCreateBitmapFromData, XCreatePixmap,  XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize, XQueryBestStipple,  XReadBitmapFile, 
XSetTile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap, 
XWriteBitmapFile. 
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—  Xlib- Color  Cells- 


J  XQueryColor 


Name 

XQueryColor  —  obtain  the  RGB  values  and  flags  for  a  specified  colorcell. 

Synopsis 

XQueryColor ( display f    cmap,    colorcell_def) 
Display   ^display; 
Colormap   cmap; 
XColor   *colorcell_def;  /*  SEND   and  RETURN    */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

cmap  Specifies  the  ID  of  the  colormap  from  which  RGB  values  will  be  retrieved. 

colorcell_def 

Specifies  the  pixel  value  and  returns  the  RGB  contents  of  that  colorcell. 

Description 

XQueryColor  returns  the  RGB  values  in  colormap  cmap  for  the  colorcell  corresponding  to 
the  pixel  value  specified  in  the  pixel  member  of  the  XColor  structure  colorcell_def . 
The  RGB  values  are  returned  in  the  red,  green,  and  blue  members  of  that  structure,  and  the 
flags  member  of  that  structure  is  set  to  (DoRed  I  DoGreen  |  DoBlue) .  The  values 
returned  for  an  unallocated  entry  are  undefined. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 
Structures 

typedef  struct  { 

unsigned  long  pixel; 

unsigned  short  red,  green,  blue; 

char  flags;  /*  DoRed,  DoGreen,  DoBlue  */ 

char  pad; 
}  XColor; 

Errors 

BadColormap 

BadValue          Pixel  not  valid  index  into  cmap. 

Related  Commands 

BlackPixel,  WhitePixel, XAllocColor,  XAllocColorCells, XAllocColor- 
Planes,  XAllocNamedColor, XFreeColors, XLookupColor,  XParseColor, 
XQueryColors, XStoreColor, XStoreColors,  XStoreNamedColor. 
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XQueryColors 


Xlib- Color  Cells- 


Name 

XQueryColors  —  obtain  RGB  values  for  an  array  of  colorcells. 

Synopsis 

XQueryColors (display,    cmap,    colorcell_defs ,    ncolors) 
Display    *display; 
Colormap    cmap; 

XColor    color cell_defs  [ncolors]  ;          /*  SEND   and  RETURN    */ 
int    ncolors; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

cmap  Specifies  the  ID  of  the  colormap  from  which  RGB  values  will  be  retrieved. 

colorcell_defs 

Specifies  an  array  of  XColor  structures.  In  each  one,  pixel  is  set  to  indi 
cate  which  colorcell  in  the  colormap  to  return,  and  the  RGB  values  in  that 
colorcell  are  returned  in  red,  green,  and  blue. 

ncol  ors  Specifies  the  number  of  XColor  structures  in  the  color  definition  array. 

Description 

XQueryColors  is  similar  to  XQueryColor,  but  it  returns  an  array  of  RGB  values.  It 
returns  the  RGB  values  in  colormap  cmap  for  the  colorcell  corresponding  to  the  pixel  value 
specified  in  the  pixel  member  of  the  XColor  structure  colorcell_def .  The  RGB  values 
are  returned  in  the  red,  green,  and  blue  members  of  that  same  structure,  and  sets  the 
flags  member  in  each  XColor  structure  to  (DoRed  I  DoGreen  |  DoBlue). 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 
Structures 

typedef  struct  { 

unsigned  long  pixel; 

unsigned  short  red,  green,  blue; 

char  flags;  /*  DoRed,  DoGreen,  DoBlue  */ 

char   pad; 
}    XColor; 

Errors 

BadColormap  Specified  colormap  does  not  exist. 

BadValue          Pixel  not  valid  index  into  cmap. 

Note:  if  more  than  one  pixel  value  is  in  error,  the  one  reported  is  arbitrary. 

Related  Commands 

BlackPixel, WhitePixel, XAllocColor, XAllocColorCells, XAllocColor- 
Planes,  XAllocNamedColor, XFreeColors, XLookupColor,  XParseColor, 
XQueryColor, XStoreColor, XStoreColors,  XStoreNamedColor. 
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— Xlib  -  Extensions- 


J  XQueryExtension 


Name 

XQueryExtension  —  get  extension  information. 

Synopsis 

Bool   XQueryExtension ( display,  name,    major_opcodef 

first_eventr     first_error) 
Display    ^display; 
char    *name; 

int    *major_opcode;  /*  RETURN    */ 

int    *first_event ;  /*  RETURN    */ 

int    *first_error;  /*  RETURN    */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

name  Specifies  the  name  of  the  desired  extension.  Upper  or  lower  case  is  impor 

tant.  The  string  should  be  in  ISO  LATIN- 1  encoding,  which  means  that  the 
first  128  character  codes  are  ASCII,  and  the  second  128  character  codes  are 
for  special  characters  needed  in  western  languages  other  than  English. 

major_opcode 

Returns  the  major  opcode  of  the  extension,  for  use  in  error  handling  routines. 

first_event  Returns  the  code  of  the  first  custom  event  type  created  by  the  extension. 
f  irst_error  Returns  the  code  of  the  first  custom  error  defined  by  the  extension. 

Description 

XQueryExtension  determines  if  the  named  extension  is  present,  and  returns  True  if  it  is. 
If  so,  the  routines  in  the  extension  can  be  used  just  as  if  they  were  core  Xlib  requests,  except 
that  they  may  return  new  types  of  events  or  new  error  codes.  The  available  extensions  can  be 
listed  with  XListExtensions. 

The  major_opcode  for  the  extension  is  returned,  if  it  has  one.  Otherwise,  zero  is  returned. 
This  opcode  will  appear  in  errors  generated  in  the  extension. 

If  the  extension  involves  additional  event  types,  the  base  event  type  code  is  returned  in 
first__event.  Otherwise,  zero  is  returned  in  first_event.  The  format  of  the  events  is 
specific  to  the  extension. 

If  the  extension  involves  additional  error  codes,  the  base  error  code  is  returned  in 
first_error.  Otherwise,  zero  is  returned.  The  format  of  additional  data  in  the  errors  is 
specific  to  the  extension. 

See  Volume  One,  Chapter  13,  Other  Programming  Techniques,  for  more  information  on  using 
extensions,  and  Volume  One,  Appendix  C,  Writing  Extensions  to  X,  for  information  on  writing 
them. 

Related  Commands 

XFreeExtensionList, XListExtensions. 
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XQueryFont  , X|ib  FOM>_ 

Name 

XQueryFont  —  return  information  about  a  loaded  font. 

Synopsis 

XFontStruct  *XQueryFont ( display,  font_ID) 
Display  * display; 
XID  font_ID; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

font_io  Specifies  either  the  font  ID  or  the  graphics  context  ID.  You  can  declare  the 

data  type  for  this  argument  as  either  Font  or  GContext  (both  X  IDs).  If 
GContext,  the  font  in  that  GC  will  be  queried. 

Description 

XQueryFont  returns  a  pointer  to  an  XFontStruct  structure  containing  information 
describing  the  specified  font.  This  call  is  needed  if  you  loaded  the  font  with  XLoadFont,  but 
need  the  font  information  for  multiple  calls  to  determine  the  extent  of  text.  XLoadQuery- 
Font  combines  these  two  operations. 

If  the  font  hasn't  been  loaded  (or  the  font  ID  passed  is  invalid),  XQueryFont  returns  NULL. 

If  font_lD  is  declared  as  data  type  GContext  (also  a  resource  ID),  this  function  queries  the 
font  specified  by  the  font  component  of  the  GC  specified  by  this  ID.  This  is  useful  for  getting 
information  about  the  default  font,  whose  ID  is  stored  in  the  default  GC.  However,  in  this  case 
the  GContext  ID  will  be  the  ID  stored  in  the  fid  field  of  the  returned  XFontStruct,  and 
you  can't  use  that  ID  in  XSetFont  or  XUnloadFont,  since  it  is  not  itself  the  ID  of  the  font. 

Use  XFreeFont  to  free  this  data. 

For  more  information  on  fonts,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Errors 

BadFont 

Structures 

typedef  struct  { 

XExtData  *ext_data;  /*  hook  for  extension  to  hang  data  */ 

Font  fid;  /*  font  ID  for  this  font  */ 

unsigned  direction;  /*  hint  about  direction  font  is  painted  */ 

unsigned  min_char_or_byte2;  /*  first  character  */ 

unsigned  max_char_or_byte2;  /*  last  character  */ 

unsigned  min_bytel;  /*  first  row  that  exists  */ 

unsigned  max_bytel;  /*  last  row  that  exists  */ 

Bool  all_chars_exist;  /*  flag  if  all  characters  have  nonzero  size*/ 

unsigned  default_char;  /*  char  to  print  for  undefined  character  */ 

int  n_properties;  /*  how  many  properties  there  are  */ 

XFontProp  *properties;  /*  pointer  to  array  of  additional  properties*/ 

XCharStruct  min_bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  max__bounds;  /*  minimum  bounds  over  all  existing  char*/ 


350  Xlib  Reference  Manual 


Xllb  -  Fonts 


(continued) 


XQueryFont 


XCharStruct 
int  ascent; 
int  descent; 

XFontStruct; 


•per  char; 


/*  first_char  to  last_char  information  */ 

/*  logical  extent  above  baseline  for  spacing  */ 

/*  logical  descent  below  baseline  for  spacing  */ 


Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o,  XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts,  XListFontsWith- 
Inf o, XLoadFont, XLoadQueryFont, XSetFont,  XSetFontPath,  XUnloadFont. 
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XQueryKeymap  \ X|ib  _  Keyboard_ 

Name 

XQueryKeymap  —  obtain  a  bit  vector  for  the  current  state  of  the  keyboard. 

Synopsis 

XQue  r yKeymap  (  di  spl  ay,    keys ) 
Display   *  display; 
char   keys  [32]  ;  /*  RETURN    */ 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD  i  sp  1  ay . 

keys  Returns  an  array  of  bytes  that  identifies  which  keys  are  pressed  down.  Each 

bit  represents  one  key  of  the  keyboard. 

Description 

XQueryKeymap  returns  a  bit  vector  for  the  logical  state  of  the  keyboard,  where  each  bit  set  to 
1  indicates  that  the  corresponding  key  is  currently  pressed  down.  The  vector  is  represented  as 
32  bytes.  Byte  N  (from  0)  contains  the  bits  for  keys  8N  to  8N+7  with  the  least  significant  bit  in 
the  byte  representing  key  8N.  Note  that  the  logical  state  may  lag  the  physical  state  if  device 
event  processing  is  frozen  due  to  a  grab. 

Related  Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry,  XFreeModif iermap, 
XGetKeyboardMapping, XGetModif ierMapping,  XInsertModif iermapEntry, 
XKeycodeToKeysym,  XKeysymToKeycode, XKeysymToString,  XLookupKeysym, 
XLookupString, XNewModif ierMap, XRebindKeysym,  XRef reshKeyboard- 
Mapping, XSetModif ierMapping, XStringToKeysym. 
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—  Xlib-Pointer- 


J  XQueryPointer 


Name 

XQueryPointer  —  get  the  current  pointer  location. 

Synopsis 

Bool   XQueryPointer (display,    w,    root,    child,    root_x ,    root_y , 

win_x,    win_y,    keys_buttons) 
Display    *display; 
Window   w; 

Window    *root,    *child;  /*  RETURN    */ 

int    *root_x,     *root_y;  /*   RETURN    */ 

int    *win_x,     *win_y;  /*   RETURN    */ 

unsigned   int    *keys_buttons /       /*  RETURN    */ 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

w  Specifies  a  window  which  indicates  which  screen  the  pointer  position  is 

returned  for,  and  child  will  be  a  child  of  this  window  if  pointer  is  inside  a 
child. 

root  Returns  the  root  window  ID  the  pointer  is  currently  on. 

child  Returns  the  ID  of  the  child  of  w  the  pointer  is  located  in,  or  zero  if  it  not  in  a 

child. 

root_x          Return  the  x  and  y  coordinates  of  the  pointer  relative  to  the  root's  origin. 
root_y 

win_x  Return  the  x  and  y  coordinates  of  the  pointer  relative  to  the  origin  of  window  w. 

win_y 

keys_buttons 

Returns  the  current  state  of  the  modifier  keys  and  pointer  buttons.  This  is  a 
mask  composed  of  the  OR  of  any  number  of  the  following  symbols:  Shift - 
Mask,  LockMask,  ControlMask,  ModlMask,  Mod2Mask,  ModSMask, 
Mod4Mask,  ModSMask,  ButtonlMask,  Button2Mask,  ButtonSMask, 
Button4Mask, ButtonSMask. 

Description 

XQueryPointer  gets  the  pointer  coordinates  relative  to  a  window  and  relative  to  the  root 
window,  the  root  window  ID  and  the  child  window  ID  (if  any)  the  pointer  is  currently  in, 
and  the  current  state  of  modifier  keys  and  buttons. 

If  XQueryPointer  returns  False,  then  the  pointer  is  not  on  the  same  screen  as  v,  child  is 
None,  and  win_x  and  win_y  are  zero.  However,  root,  root_x,  and  root_y  are  still 
valid.  If  XQueryPointer  returns  True,  then  the  pointer  is  on  the  same  screen  as  the  win 
dow  v/,  and  all  return  values  are  valid. 

The  logical  state  of  the  pointer  buttons  and  modifier  keys  can  lag  behind  their  physical  state  if 
device  event  processing  is  frozen  due  to  a  grab. 
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XQueryPointer  (continued)  Xllb  -  Pointer 

Errors 

BadWindow 

Related  Commands 

XChangeActivePointerGrab,  XChangePointerControl,  XGetPointer- 
Control,  XGetPointerMapping, XGrabPointer,  XSetPointerMapping, 
XUngrabPointer,  XWarpPointer. 
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—  Xlib-Text- 


J  XQueryTextExtents 


Name 

XQueryTextExtents  —  query  the  server  for  string  and  font  metrics. 
Synopsis 

XQueryTextExtents ( display,  font_ID,  string,  nchars, 

direction,  ascent,  descent,  overall) 
Display  *display; 
XID  font_ID; 
char  *string; 
int  nchars; 

int  * direct  ion;  /*  RETURN  */ 

int  * ascent,  * descent;     /*  RETURN  */ 
XCharStruct  *overall;      /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

font_lD  Specifies  the  appropriate  font  ID  previously  returned  by  XLoadFont,  or  the 

GContext  that  specifies  the  font. 

string  Specifies  the  character  string  for  which  metrics  are  to  be  returned. 

nchars  Specifies  the  number  of  characters  in  string. 

direction       Returns  the  direction  the  string  would  be  drawn  using  the  specified  font. 
Either  FontLef  tToRight  or  FontRightToLef  t. 

ascent  Returns  the  maximum  ascent  for  the  specified  font. 

descent  Returns  the  maximum  descent  for  the  specified  font. 

overall  Returns  the  overall  characteristics  of  the  string.  These  are  the  sum  of  the 

width  measurements  for  each  character,  the  maximum  ascent  and 
descent,  the  minimum  Ibearing  added  to  the  width  of  all  characters  up 
to  the  character  with  the  smallest  Ibearing,  and  the  maximum  rbearing 
added  to  the  width  of  all  characters  up  to  the  character  with  the  largest 
rbearing. 

Description 

XQueryTextExtents  returns  the  dimensions  in  pixels  that  specify  the  bounding  box  of  the 
specified  string  of  characters  in  the  named  font,  and  the  maximum  ascent  and  descent  for  the 
entire  font.  This  function  queries  the  server  and,  therefore,  suffers  the  round  trip  overhead  that 
is  avoided  by  XTextExtents,  but  XQueryTextExtents  does  not  require  a  filled  XFont- 
Inf  o  structure  stored  on  the  client  side.  Therefore,  this  would  be  used  when  memory  is  pre 
cious,  or  when  just  a  small  number  of  text  width  calculations  are  to  be  done. 

The  returned  ascent  and  descent  should  usually  be  used  to  calculate  the  line  spacing, 
while  the  width,  rbearing,  and  Ibearing  members  of  overall  should  be  used  for  hori 
zontal  measures.  The  total  height  of  the  bounding  rectangle,  good  for  any  string  in  this  font,  is 

ascent + descent. 
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XQueryTextExtentS  (continued)  Xlib  -  Text 

overall .  ascent  is  the  maximum  of  the  ascent  metrics  of  all  characters  in  the  string.  The 
overall .  descent  is  the  maximum  of  the  descent  metrics.  The  overall .  width  is  the 
sum  of  the  character-width  metrics  of  all  characters  in  the  string.  The  overall .  Ibearing 
is  usually  the  Ibearing  of  the  first  character  in  the  string,  and  overall .  rbearing  is  the 
rbearing  of  the  last  character  in  the  string  plus  the  sum  of  the  widths  of  all  the  characters  up  to 
but  not  including  the  last  character.  More  technically,  here  is  the  X  protocol  definition:  For 
each  character  in  the  string,  let  W  be  the  sum  of  the  character-width  metrics  of  all  characters 
preceding  it  in  the  string,  let  L  be  the  Ibearing  metric  of  the  character  plus  W,  and  let  R  be  the 
rbearing  metric  of  the  character  plus  W.  The  overall .  Ibearing  is  the  minimum  L  of  all 
characters  in  the  string,  and  the  overall .  rbearing  is  the  maximum  R. 

For  more  information  on  drawing  text,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and 
Text. 

Structures 

typedef  struct  { 

short  Ibearing;  /*  origin  to  left  edge  of  character  */ 

short  rbearing;  /*  origin  to  right  edge  of  character  */ 

short  width;  /*  advance  to  next  char's  origin  */ 

short  ascent;  /*  baseline  to  top  edge  of  character  */ 

short  descent;  /*  baseline  to  bottom  edge  of  character  */ 
unsigned  short  attributes;  /*  per  char  flags  (not  predefined)  */ 

}  XCharStruct; 

Errors 

BadFont 

Related  Commands 

XDrawImageString, XDrawImageStringl6, XDrawString, XDrawStringl6, 
XDrawText, XDrawTextl6, XQueryTextExtentS 16, XTextExtents,  XText- 
Extentsl6, XTextWidth,  XTextWidthlG. 
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—  Xlib-Text- 


J  XQueryTextExtentsI  6 


Name 

XQueryTextExtentsI 6  —  query  the  server  for  string  and  font  metrics  of  a  16-bit  character 
string. 

Synopsis 

XQueryTextExtentsI 6 (display,  font_ID,  string,  nchars, 

direction,  ascent,  descent,  overall) 
Display  * display; 
XID  font_ID; 
XChar2b  *string; 
int  nchars; 

int  * direct  ion;  /*  RETURN  */ 

int  *ascent,  *descent;     /*  RETURN  */ 
XCharStruct  *  overall;      /*  RETURN  */ 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  xopenD i splay. 

font_TD  Specifies  the  appropriate  font  ID  previously  returned  by  XLoadFont,  or  the 

GContext  that  specifies  the  font. 

string  Specifies  the  character  string  for  which  metrics  are  to  be  returned. 

nchars  Specifies  the  number  of  characters  in  string. 

direction       Returns  the  direction  of  painting  in  the  specified  font.  Either  FontLef  tto- 

Right  or  FontRighttoLef t. 

a  scent  Returns  the  maximum  ascent  in  pixels  for  the  specified  font. 

descent  Returns  the  maximum  descent  in  pixels  for  the  specified  font. 

overall  Returns  the  overall  characteristics  of  the  string.  These  are  the  sum  of  the 

width  measurements  for  each  character,  the  maximum  ascent  and 
descent,  the  minimum  Ibearing  added  to  the  width  of  all  characters  up 
to  the  character  with  the  smallest  Ibearing,  and  the  maximum  rbearing 
added  to  the  width  of  all  characters  up  to  the  character  with  the  largest 
rbearing. 

Description 

XQueryTextExtentsI 6  returns  the  dimensions  in  pixels  that  specify  the  bounding  box  of 
the  specified  string  of  characters  in  the  named  font,  and  the  maximum  ascent  and  descent  for 
the  entire  font.  This  function  queries  the  server  and,  therefore,  suffers  the  round  trip  overhead 
that  is  avoided  by  XTextExtentslG,  but  XQueryTextExtents  does  not  require  a  filled 
XFontlnf  o  structure. 

The  returned  ascent  and  descent  should  usually  be  used  to  calculate  the  line  spacing, 
while  the  width,  rbearing,  and  Ibearing  members  of  overall  should  be  used  for  hori 
zontal  measures.  The  total  height  of  the  bounding  rectangle,  good  for  any  string  in  this  font,  is 

ascent  +  descent. 
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overall .  ascent  is  the  maximum  of  the  ascent  metrics  of  all  characters  in  the  string.  The 
overall .  descent  is  the  maximum  of  the  descent  metrics.  The  overall .  width  is  the 
sum  of  the  character-width  metrics  of  all  characters  in  the  string.  The  overall .  Ibearing 
is  usually  the  Ibearing  of  the  first  character  in  the  string,  and  overall .  rbearing  is  the 
rbearing  of  the  last  character  in  the  string  plus  the  sum  of  the  widths  of  all  the  characters  up  to 
but  not  including  the  last  character.  More  technically,  here  is  the  X  protocol  definition:  For 
each  character  in  the  string,  let  W  be  the  sum  of  the  character-width  metrics  of  all  characters 
preceding  it  in  the  string,  let  L  be  the  Wearing  metric  of  the  character  plus  W,  and  let  R  be  the 
rbearing  metric  of  the  character  plus  W.  The  overall .  Ibearing  is  the  minimum  L  of  all 
characters  in  the  string,  and  the  overall .  rbearing  is  the  maximum  R. 

For  fonts  defined  with  linear  indexing  rather  than  two-byte  matrix  indexing,  the  server  inter 
prets  each  XChar2b  as  a  16-bit  number  that  has  been  transmitted  with  the  most  significant 
byte  first.  That  is,  byte  one  of  the  XChar2b  is  taken  as  the  most  significant  byte. 

If  the  font  has  no  defined  default  character,  then  undefined  characters  in  the  string  are  taken  to 
have  all  zero  metrics. 

Structures 

typedef  struct  {  /*  normal  16-bit  characters  are  two  bytes  */ 

unsigned  char  bytel; 

unsigned  char  byte2; 
}  XChar2b; 

typedef  struct  { 

short  Ibearing;  /*  origin  to  left  edge  of  character  */ 

short  rbearing;  /*  origin  to  right  edge  of  character  */ 

short  width;  /*  advance  to  next  char's  origin  */ 

short  ascent;  /*  baseline  to  top  edge  of  character  */ 

short  descent;  /*  baseline  to  bottom  edge  of  character  */ 
unsigned  short  attributes;  /*  per  char  flags  (not  predefined)  */ 

}  XCharStruct; 

Errors 

BadFont 

Related  Commands 

XDrawImageString, XDrawImageStringlG, XDrawString,  XDrawStringlG, 
XDrawText, XDrawTextlS,  XQueryTextExtents, XTextExtents,  XText- 
Extentsl6,  XTextWidth,  XTextWidthl6. 
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Name 

XQueryTree  —  return  a  list  of  children,  parent,  and  root. 

Synopsis 

Status  XQueryTree  (  display,  w 

nchildren) 
Display  *display; 
Window  w; 

Window  *root;  /*  RETURN 

Window  *parent ;  /*  RETURN 

Window  ** children;         /*  RETURN 
unsigned  int  * nchildren;   /*  RETURN 


XQueryTree 


root,    parent,    children, 


*/ 
*/ 
*/ 
*/ 


Arguments 

display 


Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  to  be  queried.   For  this  window,  XQuery 

Tree  will  list  its  children,  its  root,  its  parent,  and  the  number  of  children. 

root  Returns  the  root  ID  for  the  specified  window. 

parent  Returns  the  parent  window  of  the  specified  window. 

children         Returns  the  list  of  children  associated  with  the  specified  window. 
nchildren       Returns  the  number  of  children  associated  with  the  specified  window. 
Description 

XQueryTree  uses  its  last  four  arguments  to  return  the  root  ID,  the  parent  ID,  a  pointer  to  a  list 
of  children  and  the  number  of  children  in  that  list,  all  for  the  specified  window  w.  The  chil 
dren  are  listed  in  current  stacking  order,  from  bottommost  (first)  to  topmost  (last).  XQuery 
Tree  returns  zero  if  it  fails,  nonzero  if  it  succeeds. 

You  should  deallocate  the  list  of  children  with  XFree  when  it  is  no  longer  needed. 

Errors 

BadWindow 

Related  Commands 

XCirculateSubwindows, XCirculateSubwindowsDown,  XCirculate- 
SubwindowsUp, XConf igureWindow, XLowerWindow,  XMoveResizeWindow, 
XMoveWindow,  XRaiseWindow, XReparentWindow,  XResizeWindow,  XRestack- 
Windows. 
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XRaiseWindow 

•Xlib  -  Window  Manipulation  — 

Name 

XRaiseWindow  —  raise  a  window  to  the  top  of  the  stacking  order. 

Synopsis 

XRaiseWindow  (display,  v/) 
Display  *display; 
Window  w; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  to  be  raised  to  the  top  of  the  stack. 

Description 

XRaiseWindow  moves  a  window  to  the  top  of  the  stacking  order  among  its  siblings.  If  the 
windows  are  regarded  as  overlapping  sheets  of  paper  stacked  on  a  desk,  then  raising  a  window 
is  analogous  to  moving  the  sheet  to  the  top  of  the  stack,  while  leaving  its  x  and  y  location  on 
the  desk  constant. 

Raising  a  mapped  window  may  generate  exposure  events  for  that  window  and  any  mapped 
subwindows  of  that  window  that  were  formerly  obscured. 

If  the  override_redirect  attribute  of  the  window  (see  Volume  One,  Chapter  4,  Window 
Attributes)  is  False  and  the  window  manager  has  selected  SubstructureRedirectMask 
on  the  parent,  then  a  Conf  igureRequest  event  is  sent  to  the  window  manager,  and  no  fur 
ther  processing  is  performed. 

Errors 

BadWindow 

Related  Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp,  XConf igureWindow,  XLowerWindow,  XMoveResizeWindow, 
XMoveWindow, XQueryTree, XRepa rent Window, XResizeWindow,  XRestack- 
Windows. 
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j  XReadBitmapFlle 


Name 

XReadBitmapFile  —  read  a  bitmap  from  disk. 

Synopsis 

int  XReadBitmapFile (display,  drawable,  filename,  width, 

height,  bitmap,  x_hot,  y_hot) 
Display  * display ; 
Drawable  drawable; 
char  *  filename; 

unsigned  int  * width,  *  height;       /*  RETURN  */ 
Pixmap  *  bitmap;  /*  RETURN  */ 

int  *x_hot,  *y_hot;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

dr a  wabl  e         Specifies  the  drawable. 

filename         Specifies  the  filename  to  use.  The  format  of  the  filename  is  operating  system 
specific. 

width  Return  the  dimensions  in  pixels  of  the  bitmap  that  is  read. 

height 

bi  tmap  Returns  the  pixmap  resource  ID  that  is  created. 

x_hot  Return  the  hotspot  coordinates  in  the  file  (or  -1,-1  if  none  present). 

y_hot 

Description 

XReadBitmapFile  reads  in  a  file  containing  a  description  of  a  pixmap  of  depth  1  (a  bitmap) 
in  X  Version  1 1  bitmap  format. 

XReadBitmapFile  creates  a  pixmap  of  the  appropriate  size  and  reads  the  bitmap  data  from 
the  file  into  the  pixmap.  The  caller  should  free  the  pixmap  using  XFreePixmap  when  fin 
ished  with  it. 

If  the  file  cannot  be  opened,  XReadBitmapFile  returns  BitmapOpenFailed.  If  the  file 
can  be  opened  but  does  not  contain  valid  bitmap  data,  XReadBitmapFile  returns  Bitmap- 
Filelnvalid.  If  insufficient  working  storage  is  allocated,  XReadBitmapFile  returns 
BitmapNoMemory.  If  the  file  is  readable  and  valid,  XReadBitmapFile  returns  Bitmap- 
Success. 


Xlib  Reference  Manual  361 


XReadBitmapFile  (continued)  Xlib  -  Pixmaps  and  Tiles 

Here  is  an  example  X  Version  1 1  bitmap  file: 

tdefine  name_width  16 

#define  name_height  16 

#define  name_x_hot  8 

#define  name  y  hot  8 

static  char  name_bits[]  =  { 

Oxf8,  Oxlf,  Oxe3,  Oxc7,  Oxcf,  Oxf3,  Ox9f,  Oxf9,  Oxbf,  Oxfd,  0x33,  Oxcc, 

Ox7f,  Oxfe,  Ox7f,  Oxfe,  Ox7e,  Ox7e,  Ox7f,  Oxfe,  0x37,  Oxec,  Oxbb,  Oxdd, 

Ox9c,  0x39,  Oxcf,  Oxf3,  Oxe3,  Oxc7,  Oxf8,  Oxlf}; 

For  more  information,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
Errors 

BadDrawable 

Related  Commands 

XCreateBitmapFromData, XCreatePixmap,  XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile, XSet- 
Tile, XSetWindowBackgroundPixmap, XSetWindowBorderPixmap,  XWrite- 
BitmapFile. 
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—Xlib -Keyboard- 


J  XRebindKeysym 


Name 

XRebindKeysym  —  rebind  a  keysym  to  a  string  for  client. 

Synopsis 

XRebindKeysym  (display,  keysym,  mod_list,  mod_count,  string, 

num_bytes) 
Display  * display ; 
KeySym  keysym; 
KeySym  *mod_list ; 
int  mod_count; 
unsigned  char  *string; 
int  num_bytes; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

keysym  Specifies  the  keysym  to  be  rebound. 

mod_list          Specifies  a  pointer  to  an  array  of  keysyms  that  are  being  used  as  modifiers. 

mod_ count       Specifies  the  number  of  modifiers  in  the  modifier  list. 

string  Specifies  a  pointer  to  the  string  that  is  to  be  copied  and  returned  by 

XLookupString  in  response  to  later  events. 

num_bytes       Specifies  the  length  of  the  string. 
Description 

XRebindKeysym  binds  the  ASCII  string  to  the  specified  keysym,  so  that  string  and 
keysym  are  returned  by  XLookukpSt  ring  when  that  key  is  pressed  and  the  modifiers  speci 
fied  in  mod_list  are  also  being  held  down.  This  function  rebinds  the  meaning  of  a  keysym 
for  a  client.  It  does  not  redefine  the  keycode  in  the  server  but  merely  provides  an  easy  way  for 
long  strings  to  be  attached  to  keys.  Note  that  you  are  allowed  to  rebind  a  keysym  that  may  not 
exist. 

See  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer,  for  a  description  of  keysyms  and  key 
board  mapping. 

Related  Commands 

XChangeKeyboardMapping,  XDeleteModif  iermapEntry,  XFreeModif  iermap, 
XGetKeyboardMapping,  XGetModif  ierMapping,  XInsertModif  iermapEntry, 
XKeycodeToKeysym,  XKeysymToKeycode,  XKeysymToString,  XLookupKeysym, 
XLookupString, XNewModif ierMap, XQueryKeymap,  XRef reshKeyboard- 
Mapping, XSetModif ierMapping, XStringToKeysym. 
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Name 

XRecolorCursor  —  change  the  color  of  a  cursor. 

Synopsis 

XRecolorCursor ( display,  cursor,  foreground_colorr 

background_color) 
Display  * display; 
Cursor  cursor; 
XColor  *foreground_colorf  *background_color ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

cursor  Specifies  the  cursor  ID. 

foreground_col or 

Specifies  the  red,  green,  and  blue  (RGB)  values  for  the  foreground. 

background_color 

Specifies  the  red,  green,  and  blue  (RGB)  values  for  the  background. 

Description 

XRecolorCursor  applies  a  foreground  and  background  color  to  a  cursor.  Cursors  are  nor 
mally  created  using  a  single  plane  pixmap,  composed  of  O's  and  1's,  with  one  pixel  value 
assigned  to  1's  and  another  assigned  to  O's.  XRecolorCursor  changes  these  pixel  values.  If 
the  cursor  is  being  displayed  on  a  screen,  the  change  is  visible  immediately.  On  some  servers, 
these  color  selections  are  read/write  cells  from  the  colormap,  and  can't  be  shared  by  applica 
tions. 

Structures 

typedef  struct  { 

unsigned  long  pixel; 

unsigned  short  red,  green,  blue; 

char  flags;  /*  DoRed,  DoGreen,  DoBlue  */ 

char  pad; 
}  XColor; 

Errors 

BadCursor 

Related  Commands 

XCreateFontCursor, XCreateGlyphCursor, XCreatePixmapCursor, XDef ine- 
Cursor, XFreeCursor, XQueryBestCursor, XQueryBestSize,  XUndef ine- 
Cursor. 
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Name 

XReconfigureWMWindow  —  request  that  a  top-level  window  be  reconfigured. 

Synopsis 

Status  XReconf igureWMWindow ( display,  w,  screen_n umber, 

value_mask,  values) 
Display  *display; 
Window  w; 

int  screen_n umber; 
unsigned  int  value_mask; 
XWindowChanges  *  values; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window. 

screen_n umber 

Specifies  the  appropriate  screen  number  on  the  host  server. 

value_mask  Specifies  which  values  are  to  be  set  using  information  in  the  values  structure. 
This  mask  is  the  bitwise  inclusive  OR  of  the  valid  configure  window  values 
bits. 

values  Specifies  a  pointer  to  the  XWindowChanges  structure. 

Availability 

Release  4  and  later. 

Description 

XReconfigureWMWindow  issues  a  Conf igurewindow  request  on  the  specified  top-level 
window.  If  the  stacking  mode  is  changed  and  the  request  fails  with  a  BadMatch  error,  the 
error  event  is  trapped  and  a  synthetic  Conf  igureRequest  event  containing  the  same  confi 
guration  parameters  is  sent  to  the  root  of  the  specified  window.  Window  managers  may  elect  to 
receive  this  event  and  treat  it  as  a  request  to  reconfigure  the  indicated  window. 

For  more  information,  see  Volume  One,  Chapter  10,  Interclient  Communication. 
Structures 

typedef  struct  { 
int  x,  y; 

int  width,  height; 
int  border_width; 
Window  sibling; 
int  stack_mode; 
}  XWindowChanges; 
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Errors 

BadValue 
BadWindow 

Related  Commands 

Xlconif yWindow, XWithdrawWindow. 
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—  Xlib  -Regions- 


J  XRectlnRegion 


Name 

XRectlnRegion  —  determine  if  a  rectangle  resides  in  a  region. 

Synopsis 

int  XRectlnRegion  (r,  x,  y,  width,  height) 
Region  r; 
int  xr  y; 
unsigned  int  width,  height; 

Arguments 

r  Specifies  the  region. 

x  Specify  the  x  and  y  coordinates  of  the  upper-left  corner  of  the  rectangle,  rela- 

y  live  to  the  region's  origin. 

width  Specify  the  width  and  height  in  pixels  of  the  rectangle. 

height 

Description 

XRectlnRegion  returns  Rectangleln  if  the  rectangle  is  completely  contained  in  the 
region  r,  RectangleOut  if  it  is  completely  outside,  and  RectanglePart  if  it  is  partially 
inside. 

Regions  are  located  using  an  offset  from  a  point  (the  region  origin)  which  is  common  to  all 
regions.  It  is  up  to  the  application  to  interpret  the  location  of  the  region  relative  to  a  drawable. 
If  the  region  is  to  be  used  as  a  clip_mask  by  calling  xsetRegion,  the  upper-left  corner  of 
region  relative  to  the  drawable  used  in  the  graphics  request  will  be  at  (xoffset  + 
clip_x_origin,  yof  f  set  +  clip_y_origin) ,  where  xoffset  and  yof  f  set  are 
the  offset  of  the  region  and  clip_x_origin  and  clip_y_origin  are  the  clip  origin  in  the 
GC  used. 

For  this  function,  the  x  and  y  arguments  are  interpreted  relative  to  the  region  origin;  no  draw- 
able  is  involved. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion, XDestroyRegion, XEmptyRegion, XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion,  XPolygonRegion, 
XSetRegion, XShrinkRegion, XSubtractRegion,  XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 
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Name 

XRefreshKeyboardMapping  —  read  keycode-keysym  mapping  from  server  into  Xlib. 

Synopsis 

XRefreshKeyboardMapping ( event ) 
XMappingEvent  *event; 

Arguments 

event  Specifies  the  mapping  event  that  triggered  this  call. 

Description 

XRefreshKeyboardMapping  causes  Xlib  to  update  its  knowledge  of  the  mapping  between 
keycodes  and  keysyms.  This  updates  the  application's  knowledge  of  the  keyboard. 

The  application  should  call  XRefreshKeyboardMapping  when  a  MappingNot  if  y  event 
occurs.  MappingNotify  events  occur  when  some  client  has  called  XChangeKeyboard- 
Mapping. 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
Structures 

typedef  struct  { 

int  type; 

unsigned  long  serial;    /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;     /*  true  if  this  came  from  a  SendEvent  request  */ 

Display  ^display;    /*  display  the  event  was  read  from  */ 

Window  window;        /*  unused  */ 

int  request;         /*  one  of  MappingModif ier,  MappingKeyboard, 
MappingPointer  */ 

int  f irst_keycode;    /*  first  keycode  */ 

int  count;  /*  defines  range  of  change  with  f irst_keycode*/ 

}  XMappingEvent; 

Related  Commands 

XChangeKeyboardMapping,  XDeleteModif  iermapEntry,  XFreeModif  iermap, 
XGetKeyboardMapping, XGetModif ierMapping,  XInsertModif iermapEntry, 
XKeycodeToKeysym,  XKeysymToKeycode,  XKeysymToString,  XLookupKeysym, 
XLookupString,  XNewModif ierMap, XQueryKeymap, XRebindKeysym,  XSet- 
Modif ierMapping,  XStringToKeysym. 
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-xnb-  save  set '  XRemoveFromSaveSet 

Name 

XRemoveFromSaveSet  —  remove  a  window  from  the  client's  save-set. 

Synopsis 

XRemoveFromSaveSet (display,  w) 
Display  * display ; 
Window  v/; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  you  want  to  remove  from  this  client's  save-set.  This 

window  must  have  been  created  by  a  client  other  than  the  client  making  this 
call. 

Description 

XRemoveFromSaveSet  removes  a  window  from  the  save-set  of  the  calling  application. 

The  save-set  is  a  safety  net  for  windows  that  have  been  reparented  by  the  window  manager, 
usually  to  provide  a  shadow  or  other  background  for  each  window.  When  the  window  manager 
dies  unexpectedly,  the  windows  in  the  save-set  are  reparented  to  their  closest  living  ancestor,  so 
that  they  remain  alive. 

This  call  is  not  necessary  when  a  window  is  destroyed  since  destroyed  windows  are  automati 
cally  removed  from  the  save-set.  Therefore,  many  window  managers  get  away  without  ever 
calling  XRemoveFromSaveSet.  See  Volume  One,  Chapter  14,  Window  Management,  for 
more  information  about  save-sets. 

Errors 

BadMatch          wnot  created  by  some  other  client. 

BadWindow 

Related  Commands 

XAddToSaveSet, XChangeSaveSet. 
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XRemoveHost  ,  .XIib-Hos,  Access- 

Name 

XRemoveHost  —  remove  a  host  from  the  access  control  list. 

Synopsis 

XRemoveHost ( display,  host) 
Display  ^display; 
XHostAddress  *host ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

host  Specifies  the  network  address  of  the  machine  to  be  removed. 

Description 

XRemoveHost  removes  the  specified  host  from  the  access  control  list  of  the  connected  server. 
The  server  must  be  on  the  same  host  as  the  process  that  calls  XRemoveHost  in  order  to 
change  the  access  control  list. 

If  you  remove  your  own  machine  from  the  access  control  list,  you  can  no  longer  connect  to  that 
server,  and  there  is  no  way  back  from  this  call  other  than  to  log  out,  edit  the  access  control  file, 
and  reset  the  server. 

The  address  data  must  be  a  valid  address  for  the  type  of  network  in  which  the  server  oper 
ates,  as  specified  in  the  family  member. 

For  TCP/IP,  the  address  should  be  in  network  byte  order.  For  the  DECnet  family,  the  server 
performs  no  automatic  swapping  on  the  address  bytes.  A  Phase  IV  address  is  two  bytes  long. 
The  first  byte  contains  the  least  significant  eight  bits  of  the  node  number.  The  second  byte  con 
tains  the  most  significant  two  bits  of  the  node  number  in  the  least  significant  two  bits  of  the 
byte,  and  the  area  in  the  most  significant  six  bits  of  the  byte. 

For  more  information  on  access  control  lists,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 

Structures 

typedef  struct  { 

int  family;  /*  for  example  Family  Internet  */ 

int  length;  /*  length  of  address,  in  bytes  */ 

char  ^address;         /*  pointer  to  where  to  find  the  bytes  */ 

}  XHostAddress; 

/*  constants  used  for  family  member  of  XHostAddress  */ 
#define  Familylnternet        0 
#define  FamilyDECnet          1 
#define  FamilyChaos  2 

Errors 

BadAccess 
BadValue 
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Related  Commands 

XAddHost, XAddHosts, XDisableAccessControl, XEnableAccessControl, 
XListHosts, XRemoveHosts,  XSetAccessControl. 
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v Xlib  -  Host  Access- 
Name 

XRemoveHosts  —  remove  multiple  hosts  from  the  access  control  list. 

Synopsis 

XRemoveHosts ( display,  hosts,  num_hosts) 
Display  * display; 
XHostAddress  *hosts; 
int  num_hosts; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

hosts  Specifies  the  list  of  hosts  that  are  to  be  removed. 

n  um_h  osts       Specifies  the  number  of  hosts  that  are  to  be  removed. 

Description 

XRemoveHosts  removes  each  specified  host  from  the  access  control  list  of  the  connected 
server.  The  server  must  be  on  the  same  host  as  the  process  that  call  XRemoveHosts,  in  order 
to  change  the  access  control  list. 

If  you  remove  your  machine  from  the  access  control  list,  you  can  no  longer  connect  to  that 
server,  and  there  is  no  way  back  from  this  call  except  to  log  out,  edit  the  access  control  file,  and 
reset  the  server. 

The  address  data  must  be  a  valid  address  for  the  type  of  network  in  which  the  server  oper 
ates,  as  specified  in  the  family  member. 

For  TCP/IP,  the  address  should  be  in  network  byte  order.  For  the  DECnet  family,  the  server 
performs  no  automatic  swapping  on  the  address  bytes.  A  Phase  IV  address  is  two  bytes  long. 
The  first  byte  contains  the  least  significant  eight  bits  of  the  node  number.  The  second  byte  con 
tains  the  most  significant  two  bits  of  the  node  number  in  the  least  significant  two  bits  of  the 
byte,  and  the  area  in  the  most  significant  six  bits  of  the  byte. 

For  more  information  on  access  control  lists,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 

Structures 

typedef  struct  { 

int  family;  /*  for  example  Family  Internet  */ 

int  length;  /*  length  of  address,  in  bytes  */ 

char  *address;          /*  pointer  to  where  to  find  the  bytes  */ 

}  XHostAddress; 

/*  constants  used  for  family  member  of  XHostAddress  */ 

tdefine  Familylnternet  0 

#define  FamilyDECnet  1 

#define  FamilyChaos  2 


372  Xlib  Reference  Manual 


Xllb  -  Host  Access  (continued)  XRemOveHoStS 


Errors 

BadAccess 
BadValue 


Related  Commands 

XAddHost, XAddHosts,  XDisableAccessControl, XEnableAccessConti 
XListHosts, XRemoveHost, XSetAccessControl. 
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Name 

XReparentWindow  —  insert  a  window  between  another  window  and  its  parent. 

Synopsis 

XReparentWindow (display,  win,  parent,  x,  y) 
Display  * display ; 
Window  win ; 
Window  parent; 
int  xr  y; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

win  Specifies  the  ID  of  the  window  to  be  reparented. 

pa  ren  t  Specifies  the  window  ID  of  the  new  parent  window. 

x  Specify  the  coordinates  of  the  window  relative  to  the  new  parent. 

y 
Description 

XReparentWindow  modifies  the  window  hierarchy  by  placing  window  win  as  a  child  of 
window  parent.  This  function  is  usually  used  by  a  window  manager  to  put  a  decoration  win 
dow  behind  each  application  window.  In  the  case  of  the  window  manager,  the  new  parent  win 
dow  must  first  be  created  as  a  child  of  the  root  window. 

If  win  is  mapped,  an  XUnmapWindow  request  is  performed  on  it  automatically,  win  is  then 
removed  from  its  current  position  in  the  hierarchy,  and  is  inserted  as  a  child  of  the  specified 
parent,  win  is  placed  on  top  in  the  stacking  order  with  respect  to  siblings. 

A  ReparentNotif  y  event  is  then  generated.  The  override_redirect  member  of  the 
structure  returned  by  this  event  is  set  to  either  True  or  False  .  Window  manager  clients  nor 
mally  should  ignore  this  event  if  this  member  is  set  to  True. 

Finally,  if  the  window  was  originally  mapped,  an  XMapWindow  request  is  performed  automati 
cally. 

Descendants  of  win  remain  descendants  of  win;  they  are  not  reparented  to  the  old  parent  of 

win. 

Normal  exposure  processing  on  formerly  obscured  windows  is  performed.  The  server  might 
not  generate  exposure  events  for  regions  from  the  initial  unmap  that  are  immediately  obscured 
by  the  final  map.  The  request  fails  if  the  new  parent  is  not  on  the  same  screen  as  the  old  parent, 
or  if  the  new  parent  is  the  window  itself  or  an  inferior  of  the  window. 
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Errors 

BadMatch         parent  not  on  same  screen  as  old  parent  of  win. 

win  has  a  ParentRelative  background  and  parent  is  not  the  same 
depth  as  win. 

parent  is  win  or  an  inferior  of  win. 
BadWindow 

Related  Commands 

XCirculateSubwindows, XCirculateSubwindowsDown,  XCirculate- 
SubwindowsUp,  XConf  igureWindow,  XLowerWindow,  XMoveResizeWindow, 
XMoveWindow,  XQueryTree,  XRaiseWindow,  XResizeWindow, XRestack- 
Windows. 
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^ Xlib  -  Screen  Saver— 

Name 

XResetScreenSaver  —  reset  the  screen  saver. 

Synopsis 

XResetScreenSaver  (display) 
Display   * display ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

Description 

XResetScreenSaver  redisplays  the  screen  if  the  screen  saver  was  activated.  This  may 
result  in  exposure  events  to  all  visible  windows  if  the  server  cannot  save  the  screen  contents.  If 
the  screen  is  already  active,  nothing  happens. 

For  more  information  on  the  screen  saver,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 

Related  Commands 

XActivateScreenSaver, XForceScreenSaver, XGetScreenSaver,  XSet- 
ScreenSaver. 
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Name 

XResizeWindow  —  change  a  window's  size. 

Synopsis 

XResizeWindow ( display,  w,  width,  height) 
Display  ^display; 
Window  w; 
unsigned  int  width,  height; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDi splay. 

w  Specifies  the  ID  of  the  window  to  be  resized. 

width  Specify  the  new  dimensions  of  the  window  in  pixels. 

height 

Description 

XResizeWindow  changes  the  inside  dimensions  of  the  window.  The  border  is  resized  to 
match  but  its  border  width  is  not  changed.  XResizeWindow  does  not  raise  the  window,  or 
change  its  origin.  Changing  the  size  of  a  mapped  window  may  lose  its  contents  and  generate  an 
Expose  event,  depending  on  the  bit_gravity  attribute  (see  Volume  One,  Chapter  4,  Win 
dow  Attributes).  If  a  mapped  window  is  made  smaller,  exposure  events  will  be  generated  on 
windows  that  it  formerly  obscured. 

If  the  override_redirect  attribute  of  the  window  is  False  and  the  window  manager  has 
selected  SubstructureRedirectMask  on  the  parent,  then  a  Conf  igureRequest  event 
is  sent  to  the  window  manager,  and  no  further  processing  is  performed. 

If  the  client  has  selected  StructureNotifyMask  on  the  window,  then  a  Conf  igure- 
Notif  y  event  is  generated  after  the  move  takes  place,  and  the  event  will  contain  the  final  size 
of  the  window. 

Errors 

BadValue 
BadWindow 

Related  Commands 

XCirculateSubwindows, XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow,  XLowerWindow,  XMoveResizeWindow, 
XMoveWindow, XQueryTree, XRaiseWindow,  XReparentWindow, XRestack- 
Windows. 
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•Xlib  -  Window  Manipulation  — 

Name 

XRestackWindows  —  change  the  stacking  order  of  siblings. 

Synopsis 

XRestackWindows ( display,  windows,  nwlndows) ; 
Display  * display; 
Window  windows [] ; 
int  nwlndows; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

windows  Specifies  an  array  containing  the  windows  to  be  restacked.  All  the  windows 

must  have  a  common  parent. 

nwlndows         Specifies  the  number  of  windows  in  the  windows  array. 

Description 

XRestackWindows  restacks  the  windows  in  the  order  specified,  from  top  to  bottom.  The 
stacking  order  of  the  first  window  in  the  windows  array  will  be  on  top,  and  the  other  windows 
will  be  stacked  underneath  it  in  the  order  of  the  array.  Note  that  you  can  exclude  other  siblings 
from  the  windows  array  so  that  the  top  window  in  the  array  will  not  move  relative  to  these 
other  siblings. 

For  each  window  in  the  window  array  that  is  not  a  child  of  the  specified  window,  a  BadMatch 
error  will  be  generated.  If  the  override_redirect  attribute  of  the  window  is  False  and 
the  window  manager  has  selected  SubstructureRedirectMask  on  the  parent,  then 
Conf  igureRequest  events  are  sent  to  the  window  manager  for  each  window  whose  over- 
ride_redirect  is  not  set,  and  no  further  processing  is  performed.  Otherwise,  the  windows 
will  be  restacked  in  top  to  bottom  order. 

Errors 

BadMatch 
BadWindow 

Related  Commands 

XCirculateSubwindows,  XCirculateSubwindowsDown,  XCirculate- 
SubwindowsUp, XConf igureWindow, XLowerWindow,  XMoveResizeWindow, 
XMoveWindow,  XQueryTree,  XRaiseWindow,  XReparentWindow, XResize- 
Window. 
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Name 

XrmDestroyDatabase  —  destroy  a  resource  database. 

Synopsis 

void  XrmDestroyDatabase ( database) 
XrmDatabase  database; 

Arguments 

da  t  abase          Specifies  the  resource  database. 

Availability 

Release  4  and  later. 

Description 

XrmDestroyDatabase  destroys  a  resource  database  and  frees  its  allocated  memory.  The 
destroyed  resource  database  should  not  be  referenced  again.  If  database  is  NULL,  Xrm 
DestroyDatabase  returns  immediately. 

For  more  information,  see  Volume  One,  Chapter  1 1,  Managing  User  Preferences. 
Related  Commands 

XrmMergeDat abases. 
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N Xlib  -  Resource  Manager — 

Name 

XrmGetFileDatabase  —  retrieve  a  database  from  a  file. 

Synopsis 

XrmDatabase  XrmGetFileDatabase (filename) 
char  * filename; 

Arguments 

filename         Specifies  the  resource  database  filename. 

Description 

XrmGetFileDatabase  opens  the  specified  file,  creates  a  new  resource  database,  and  loads 
the  database  with  the  data  read  in  from  the  file.  The  return  value  of  the  function  is  as  a  pointer 
to  the  created  database. 

The  specified  file  must  contain  lines  in  the  format  accepted  by  XrmPutLineResource.  If 
XrmGetFileDatabase  cannot  open  the  specified  file,  it  returns  NULL. 

For  more  information,  see  Volume  One,  Chapter  II,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

Related  Commands 

XrmDestroyDatabase, XrmGetResource,  XrmGetStringDatabase,  Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource,  XrmPutStringResource,  XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource,XrmQuarkToString,  XrmStringToBindingQuark- 
List,  XrmStringToQuarkList, XrmStringToQuark,  XrmUniqueQuark. 
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Name 

XrmGetResource  —  get  a  resource  from  name  and  class  as  strings. 

Synopsis 

Bool  XrmGetResource ( database,  str_name,  str_class, 

str_type,  value) 
XrmDatabase  database; 
char  *str_name; 
char  *str_class; 

char  **str__type;          /*  RETURN  */ 
XrmValue  *  value;          /*  RETURN  */ 

Arguments 

database          Specifies  the  database  that  is  to  be  used. 

st  r_name          Specifies  the  fully  specified  name  of  the  value  being  retrieved. 
str_class       Specifies  the  fully  specified  class  of  the  value  being  retrieved. 

str_type         Returns  a  pointer  to  the  representation  type  of  the  destination.  In  this  func 
tion,  the  representation  type  is  represented  as  a  string,  not  as  an  Xrm- 

Representation. 

val  ue  Returns  the  value  in  the  database.  Do  not  modify  or  free  this  data. 

Description 

The  resource  manager  manages  databases  of  resource  specifications  consisting  of  lines  contain 
ing  resource  name/class  strings  followed  by  a  colon  and  the  value  of  the  resource.  XrmGet 
Resource  retrieves  a  resource  from  the  specified  database.  It  takes  fully  specified  name  and 
class  strings,  and  returns  the  representation  and  value  of  the  matching  resource.  The  value 
returned  points  into  database  memory;  you  must  not  modify  that  data.  If  a  resource  was  found, 
XrmGetResource  returns  True.  Otherwise,  it  returns  False. 

Currently,  the  database  only  frees  or  overwrites  entries  when  new  data  is  stored  with  Xrm- 
MergeDatabases,  or  XrmPutResource  and  related  routines.  A  client  that  avoids  these 
functions  should  be  safe  using  the  address  passed  back  at  any  time  until  it  exits. 

XrmGetResource  is  very  similar  to  XrmQGetResource,  except  that  in  XrmQGet- 
Resource,  the  equivalent  arguments  to  str_name,  str_class,  and  str_type  are 
quarks  instead  of  strings. 

To  understand  how  data  is  stored  and  retrieved  from  the  database,  you  must  understand: 

1)  The  basic  components  that  make  up  the  storage  key  and  retrieval  keys. 

2)  How  keys  are  made  up  from  components. 

3)  The  two  ways  that  components  can  be  bound  together. 

4)  What  sort  of  keys  are  used  to  store  and  retrieve  data. 
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5)  How  the  storage  key  and  retrieval  keys  are  compared  to  determine  whether  they  match. 

6)  If  there  are  multiple  matches,  how  the  best  match  is  chosen  so  only  one  value  is  returned. 
Each  will  be  covered  in  turn. 

1)  The  storage  key  and  retrieval  keys  are  composed  of  a  variable  number  of  components, 
bound  together.  There  are  two  types  of  components:  names  and  classes.  By  convention, 
names  begin  with  a  lower  case  character  and  classes  begin  with  an  upper  case  character. 
Therefore,  xmh,  background,  and  toe  are  examples  of  names,  while  Xmh,  Box,  and 
Command  are  examples  of  classes.  A  name  key  (like  str_name)  consists  purely  of 
name  components.  A  class  key  (like  str_class )  consists  purely  of  class  components. 
The  retrieval  keys  are  a  pair  of  keys,  one  composed  of  purely  name  components,  the 
other  of  purely  class  components.    A  storage  key  (like  specifier  in  XrmPut- 
Resource)  consists  of  a  mixture  of  name  and  class  components. 

2)  A  key  is  composed  of  multiple  components  bound  together  in  sequence.  This  allows  you 
to  build  logical  keys  for  your  application.  For  example,  at  the  top  level,  the  application 
might  consist  of  a  paned  window  (that  is,  a  window  divided  into  several  sections)  named 
toe.  One  pane  of  the  paned  window  is  a  button  box  window  named  buttons  filled  with 
command  buttons.  One  of  these  command  buttons  is  used  to  retrieve  (include)  new 
mail  and  has  the  name  include.  This  window  has  a  fully  qualified  name  xmh .  toe .  but 
tons,  include  and  a  fully  qualified  class  Xmh.VPaned. BOX. Command.  Its  fully  quali 
fied  name  is  the  name  of  its  parent,  xmh .  toe  .buttons,  followed  by  its  name  include. 
Its  class  is  the  class  of  its  parent,  Xmh.VPaned. BOX,  followed  by  its  particular  class, 

Command. 

3)  The  components  in  a  key  can  be  bound  together  in  two  ways:  by  a  tight  binding  (a  dot 
".")  or  by  a  loose  binding  (an  asterisk  "*").  Thus  xmh. toe. background  has  three 
name  components  tightly  bound  together,  while  Xmh*Command.  foreground  uses  both  a 
loose  and  a  tight  binding.  Bindings  can  also  precede  the  first  component  (but  may  not 
follow  the  last  component).   By  convention,  if  no  binding  is  specified  before  the  first 
component,    a    tight   binding    is   assumed.     For   example,    xmh. background   and 
.xmh. background    both    begin    with    tight    bindings    before    the    xmh,    while 
*xmh .  background  begins  with  a  loose  binding. 

The  difference  between  tight  and  loose  bindings  comes  when  comparing  two  keys.  A 
tight  binding  means  that  the  components  on  either  side  of  the  binding  must  be  sequential. 
A  loose  binding  is  a  sort  of  wildcard,  meaning  that  there  may  be  unspecified  components 
between  the  two  components  that  are  loosely  bound  together.  For  example, 

xmh. toe. background  would  match  xmh*background  and  Background  but  not 
xmh .  background  or  background. 

4)  A  key  used  to  store  data  into  the  database  can  use  both  loose  and  tight  bindings.  This 
allows  you  to  specify  a  data  value  which  can  match  to  many  different  retrieval  keys.  In 
contrast,  keys  used  to  retrieve  data  from  the  database  can  use  only  tight  bindings.  You 
can  only  look  up  one  item  in  the  database  at  a  time.  Remember  also  that  a  storage  key 
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can  mix  name  and  class  components,  while  the  retrieval  keys  are  a  pair  of  keys,  one  con 
sisting  purely  of  name  (first  character  lower  case)  components  and  one  consisting  purely 
of  class  (capitalized)  components. 

5)  The  resource  manager  must  solve  the  problem  of  how  to  compare  the  pair  of  retrieval 
keys  to  a  single  storage  key.  (Actually,  to  many  single  storage  keys,  since  the  resource 
manager  will  compare  the  retrieval  keys  against  every  key  in  the  database,  but  one  at  a 
time.)  The  solution  of  comparing  a  pair  of  keys  to  a  single  key  is  simple.  The  resource 
manager  compares  component  by  component,  comparing  a  component  from  the  storage 
key  against  both  the  corresponding  component  from  the  name  retrieval  key,  and  the  cor 
responding  component  from  the  class  retrieval  key.    If  the  storage  key  component 
matches  either  retrieval  key  component,  then  that  component  is  considered  to  match.  For 
example,    the    storage    key     xmh. toe. Foreground    matches    the    name    key 
xmh  .toe  .  foreground  with  the  class  key  Xmh.  Box.  Foreground.   This  is  why 
storage  keys  can  mix  name  and  class  components,  while  retrieval  keys  cannot. 

6)  Because  the  resource  manager  allows  loose  bindings  (wildcards)  and  mixing  names  and 
classes    in  the  storage  key,  it  is  possible  for  many  storage  keys  to  match  a  single 
name/class  retrieval  key  pair.  To  solve  this  problem,  the  resource  manager  uses  the  fol 
lowing  precedence  rules  to  determine  which  is  the  best  match  (and  only  the  value  from 
that  match  will  be  returned).  The  precedence  rules  are,  in  order  of  preference: 

1.  The  attribute  of  the  name  and  class  must  match.  For  example,  queries  for 

xterm.  scrollbar. background      (name) 
XTerm.  Scrollbar.  Background      (class) 

will  not  match  the  following  database  entry: 

xterm. scrollbar:         on 

because  background  does  not  appear  in  the  database  entry. 

2.  Database  entries  with  name  or  class  prefixed  by  a  dot  ( . )  are  more  specific  than  those 
prefixed  by  an  asterisk  (*).  For  example,  the  entry  xterm .  geometry  is  more  specific 
than  the  entry  xterm*geometry. 

3.  Names  are  more  specific  than  classes.    For  example,  the  entry   *scrollbar.- 
background  is  more  specific  than  the  entry  *  Scrollbar .  Background. 

4.  A    name    or    class    is    more    specific    than    omission.     For    example,    the    entry 
Scrollbar*Background  is  more  specific  than  the  entry  *Background. 

5.  Left  components  are  more  specific  than  right  components.  For  example,  to  query  for 
.xterm.  scrollbar  .background,  the  entry  xterm*background  is  more  spe 
cific  than  the  entry  scrollbar*background. 
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Names  and  classes  can  be  mixed.  As  an  example  of  these  rules,  assume  the  following  user  pref 
erence  specification: 

xmh*background:  red 

* command. font :  8x13 

*command. background:  blue 

*Command. Foreground :  green 

xmh. toc*Command. activeForeground:  black 

A  query  for  the  name  xmh.  toe  .messagef unctions  .  include  .activeForeground 
and  class  Xmh.VPaned.  Box.  Command.  Foreground  would  match  xmh.toc*- 
Command. activeForeground  and  return  black.  However,  it  also  matches  *Com- 
mand .  Foreground  but  with  lower  preference,  so  it  would  not  return  green. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences,  and  Volume 
Four,  X  Toolkit  Intrinsics  Programming  Manual,  Chapter  9,  Resource  Management  and  Type 
Conversion. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

typedef  struct  { 

unsigned  int     size; 

caddr_t         addr; 
}  XrmValue; 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase,  XrmGetStringDatabase,  Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand,  XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource,  XrmQuarkToString,  XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark,  XrmUniqueQuark. 
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Name 

XrmGetStringDatabase  —  create  a  database  from  a  string. 

Synopsis 

XrmDatabase  XrmGetStringDatabase (data) 
char  *data; 

Arguments 

data  Specifies  the  database  contents  using  a  string. 

Description 

XrmGetStringDatabase  creates  a  new  database  and  stores  in  it  the  resources  specified  in 
data.  The  return  value  is  subsequently  used  to  refer  to  the  created  database.  XrmGet 
StringDatabase  is  similar  to  XrmGetFileDatabase,  except  that  it  reads  the  informa 
tion  out  of  a  string  instead  of  a  file.  Each  line  in  the  string  is  separated  by  a  new  line  character 
in  the  format  accepted  by  XrmPutLineResource. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

Related  Commands 

XrmDestroyDatabase,  XrmGetFileDatabase,  XrmGetResource,  Xrm- 
Initialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource,  XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource,  XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString,  XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 
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Xrmlnitialize 

Xlib  -  Resource  Manager— 

Name 

Xrmlnitialize  —  initialize  the  resource  manager. 

Synopsis 

void  Xrmlnitialize (  )  ; 

Description 

Xrmlnitialize  initializes  the  resource  manager,  and  should  be  called  once  before  using 
any  other  resource  manager  functions.  It  just  creates  a  representation  type  of  "String"  for  val 
ues  defined  as  strings.  This  representation  type  is  used  by  XrmPutStringResource  and 
XrmQPutStringResource,  which  require  a  value  as  a  string.  See  XrmQPutResource 
for  a  description  of  representation  types. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 
Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource,  XrmGet- 
StringDatabase, XrmMergeDatabases, XrmParseCommand, XrmPutFile- 
Database,  XrmPutLineResource, XrmPutResource,  XrmPutStringResource, 
XrmQGetResource, XrmQGetSearchList, XrmQGetSearchResource,  XrmQPut 
Resource,  XrmQPutStringResource, XrmQuarkToString, XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 
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J  XrmMergeDatabases 


Name 

XrmMergeDatabases  —  merge  the  contents  of  one  database  into  another. 

Synopsis 

void  XrmMergeDatabases ( source_db,  target _db) 
XrmDat abase  source_db,  *target_db; 

Arguments 

source_db       Specifies  the  resource  database  to  be  merged  into  the  existing  database. 

targe t_db       Specifies  a  pointer  to  the  resource  database  into  which  the  source_db  data 
base  will  be  merged. 

Description 

XrmMergeDatabases  merges  source_db  into  target_db.  This  procedure  is  used  to 
combine  databases,  for  example,  an  application  specific  database  of  defaults  and  a  database  of 
user  preferences.  The  merge  is  destructive;  it  destroys  the  original  source_db  database  and 
modifies  the  original  targe t_db. 

For  more  information,  see  Volume  One,  Chapter  II,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmParseCommand, XrmPutFileDatabase, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource,  XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString,  XrmStringToBindingQuark- 
List,  XrmStringToQuarkList, XrmStringToQuark,  XrmUniqueQuark. 
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XrmParseCommand  \. 

v Xlib  -  Resource  Manager- 
Name 

XrmParseCommand  —  load  a  resource  database  from  command  line  arguments. 

Synopsis 

void  XrmParseCommand ( db,  table,  table_count ,  name,  argc, 

argv) 

XrmDatabase    *db;  /*  SEND   and   if  NULL,    RETURN    */ 

XrmOptionDescList    table; 
int    table_count / 
char   *name; 

int    *argc;  /*  SEND    and  RETURN    */ 

char    **argv;  /*   SEND    and  RETURN    */ 

Arguments 

database         Specifies  a  pointer  to  the  resource  database.  If  database  contains  NULL,  a 
new  resource  database  is  created  and  a  pointer  to  it  is  returned  in  database. 

t  abl  e  Specifies  table  of  command  line  arguments  to  be  parsed. 

table_count  Specifies  the  number  of  entries  in  the  table. 
name  Specifies  the  application  name. 

argc  Before  the  call,  specifies  the  number  of  arguments.  After  the  call,  returns  the 

number  of  arguments  not  parsed. 

argv  Before  the  call,  specifies  a  pointer  to  the  command  line  arguments.  After  the 

call,  returns  a  pointer  to  a  string  containing  the  command  line  arguments  that 
could  not  be  parsed. 

Description 

XrmParseCommand  parses  an  (argc,  argv)  pair  according  to  the  specified  option  table, 
loads  recognized  options  into  the  specified  database,  and  modifies  the  (argc,  argv)  pair  to 
remove  all  recognized  options. 

The  specified  table  is  used  to  parse  the  command  line.  Recognized  entries  in  the  table  are 
removed  from  argv,  and  entries  are  made  in  the  specified  resource  database.  The  table  entries 
contain  information  on  the  option  string,  the  option  name,  which  style  of  option  and  a  value  to 
provide  if  the  option  kind  is  XrmoptionNoArg.  See  the  example  table  below. 

argc  specifies  the  number  of  arguments  in  argv  and  is  set  to  the  remaining  number  of  argu 
ments  that  were  not  parsed,  name  should  be  the  name  of  your  application  for  use  in  building 
the  database  entry,  name  is  prepended  to  the  resourceName  in  the  option  table  before  stor 
ing  the  specification.  No  separating  (binding)  character  is  inserted.  The  table  must  contain 
either  a  dot  (".")  or  an  asterisk  ("*")  as  the  first  character  in  each  resourceName  entry.  The 
resourceName  entry  can  contain  multiple  components. 

The  following  is  a  typical  options  table: 

static  XrmOptionDescRec  opTable[  ]  =  { 

{"-background",   "*background",  XrmoptionSepArg,  (caddr_t)  NULL}, 
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(continued) 


XrmParseCommand 


{"-bg", 

{"-borderwidth1 

{ "-bordercolor1 

{"-bw", 

{ "-display", 

{"-fg", 

{"-fn", 

{ "-font", 

{ "-foreground", 

{ "-geometry", 

{ "-iconic" , 

{ "-name", 

{ "-reverse" , 

-rv", 

-synchronous' 

-title", 

-xrm", 


"*borderColor", 

"* background" , 

"*TopLevelShell . borderWidth", 

"*borderColor " , 

"*TopLevelShell.borderWidth", 

".display", 

"^foreground", 

"*font", 

"*font", 

"*foreground", 

" .TopLevelShell .geometry", 

" .TopLevelShell . iconic", 

" .name", 

"*reverseVideo" , 

"*reverseVideo", 

11 .  synchronous", 

11 .  TopLevelShell .  title" , 

NULL, 


XrmoptionSepArg, 

(caddr_t) 

NULL} 

XrmoptionSepArg, 

(caddr_t) 

NULL} 

XrmoptionSepArg, 

(caddr_t) 

NULL} 

XrmoptionSepArg, 

(caddr_t) 

NULL} 

XrmoptionSepArg, 

(caddr  t) 

NULL} 

XrmoptionSepArg, 

(caddr_t) 

NULL} 

XrmoptionSepArg, 

(caddr  t) 

NULL} 

XrmoptionSepArg, 

(caddr_t) 

NULL} 

XrmoptionSepArg, 

(caddr_t) 

NULL} 

XrmoptionSepArg, 

(caddr_t) 

NULL} 

XrmoptionSepArg, 

(caddr  t) 

NULL} 

XrmoptionNoArg, 

(caddr_t) 

"on"  } 

XrmoptionSepArg, 

(caddr  t) 

NULL} 

XrmoptionNoArg, 

(caddr_t) 

"on"  } 

XrmoptionNoArg, 

(caddr  t) 

"on"  } 

XrmoptionNoArg, 

(caddr_t) 

"on"} 

XrmoptionSepArg, 

(caddr  t) 

NULL} 

XrmoptionResArg, 

(caddr  t) 

NULL} 

In  this  table,  if  the  -background  (or  -bg)  option  is  used  to  set  background  colors,  the  stored 
resource  specifier  will  match  all  resources  of  attribute  background.  If  the  -borderwidth  option 
is  used,  the  stored  resource  specifier  applies  only  to  border  width  attributes  of  class  Top 
LevelShell  (that  is,  outermost  windows,  including  pop-up  windows).  If  the  -title  option  is 
used  to  set  a  window  name,  only  the  topmost  application  windows  receive  the  resource. 

When  parsing  the  command  line,  any  unique  unambiguous  abbreviation  for  an  option  name  in 
the  table  is  considered  a  match  for  the  option.  Note  that  upper  case  and  lower  case  matter. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 


typedef  enum  { 

XrmoptionNoArg, 

XrmoptionlsArg, 

XrmoptionStickyArg, 

XrmoptionSepArg, 

XrmoptionResArg, 

Xrmopt ionSkipArg, 

XrmoptionSkipLine, 

XrmoptionSkipNArgs 

}  XrmOptionKind; 

typedef  struct  { 

char  *option; 
char  *resourceName; 
XrmOptionKind  argKind; 
caddr  t  value; 


/*  value  is  specified  in  OptionDescRec. value  */ 

/*  value  is  the  option  string  itself  */ 

/*  value  is  chars  immediately  following  option  */ 

/*  value  is  next  argument  in  argv  */ 

/*  resource  and  value  in  next  argument  in  argv  */ 

/*  ignore  this  option  and  next  argument  in  argv  */ 

/*  ignore  this  option  and  the  rest  of  argv  */ 

/*  new  in  R4 :  ignore  this  option,  skip 

number  specified  in  next  argument  */ 


/*  option  specification  string  in  argv  */ 

/*  binding  &  resource  name  (w/out  application  name) 

/*  which  style  of  option  it  is  */ 

/*  value  to  provide  if  XrmoptionNoArg  */ 


XrmOptionDescRec,  *XrmOptionDescList; 
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Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase,  XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmPutFile- 
Database,  XrmPutLineResource, XrmPutResource,  XrmPutStringResource, 
XrmQGetResource, XrmQGetSearchList,  XrmQGetSearchResource, XrmQPut- 
Resource,  XrmQPutStringResource, XrmQuarkToString,  XrmString- 
ToBindingQuarkList, XrmStringToQuarkList,  XrmStringToQuark,  Xrm- 
UniqueQuark. 


390  Xlib  Reference  Manual 


-XHb  -  Resource  Manager /  XrmPutFileDatabaSe 

Name 

XrmPutFileDatabase  —  store  a  resource  database  in  a  file. 

Synopsis 

void  XrmPutFileDatabase (  database,  stored_db) 
XrmDatabase  database; 
char  *stored_db; 

Arguments 

database          Specifies  the  resource  database  that  is  to  be  saved. 

stored_db       Specifies  the  filename  for  the  stored  database. 
Description 

XrmPutFileDatabase  stores  a  copy  of  the  application's  current  database  in  the  specified 
file.  The  file  is  an  ASCII  text  file  that  contains  lines  in  the  format  that  is  accepted  by  XrmPut- 
LineResource. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases,  XrmParseCommand, 
XrmPutLineResource, XrmPutResource, XrmPutStringResource, XrmQGet- 
Resource,  XrmQGetSearchList, XrmQGetSearchResource, XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString,  XrmStringToBindingQuark- 
List,  XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 
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v Xlib  -  Resource  Manager — 

Name 

XrmPutLineResource  —  add  a  resource  specification  to  a  resource  database. 

Synopsis 

void  XrmPutLineResource (database,  line) 

XrmDatabase  *database;  /*  SEND,  and  if  NULL,  RETURN  */ 
char  *line; 

Arguments 

database         Specifies  a  pointer  to  the  resource  database.  If  database  contains  NULL,  a 
new  resource  database  is  created  and  a  pointer  to  it  is  returned  in  database. 

line  Specifies  the  resource  name  (possibly  with  multiple  components)  and  value 

pair  as  a  single  string,  in  the  format  resource :  value. 

Description 

XrmPutLineResource  adds  a  single  resource  entry  to  the  specified  database. 

XrmPutLineResource  is  similar  to  XrmPutStringResource,  except  that  instead  of 
having  separate  string  arguments  for  the  resource  and  its  value,  XrmPutLineResource 
takes  a  single  string  argument  (line)  which  consists  of  the  resource  name,  a  colon,  then  the 
value.  Since  the  value  is  a  string,  it  is  stored  into  the  database  with  representation  type 

String. 

Any  whitespace  before  or  after  the  name  or  colon  in  the  line  argument  is  ignored.  The  value 
is  terminated  by  a  new-line  or  a  NULL  character.  The  value  may  contain  embedded  new-line 
characters  represented  by  the  "\"  and  "n"  two  character  pair  (not  the  single  "\n"  character), 
which  are  converted  into  a  single  linefeed  character.  In  addition,  the  value  may  run  over  onto 
the  next  line,  this  is  indicated  by  a  "\"  character  at  the  end  of  each  line  to  be  continued. 

Null-terminated  strings  without  a  new  line  are  also  permitted.  XrmPutResource,  Xrm- 
QPutResource,  XrmPutStringResource,  XrmQPutStringResource  and  Xrm 
PutLineResource  all  store  data  into  a  database.  See  XrmQPutResource  for  the  most 
complete  description  of  this  process. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 
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Related  Commands 

XrmDestroyDatabase,  XrmGetFileDatabase,  XrmGetResource,  XrmGet- 
StringDatabase, Xrmlnitialize,  XrmMergeDatabases,  XrmParseCommand, 
XrmPutFileDatabase, XrmPutResource, XrmPutStringResource,  XrmQGet- 
Resource,  XrmQGetSearchList,  XrmQGetSearchResource, XrmQPut Re source, 
XrmQPutStringRe source, XrmQuarkToString,  XrmStringToBindingQuark- 
List,  XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 
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XrmPutResource  \ 

v Xhb  -  Resource  Manager  — 

Name 

XrmPutResource  —  store  a  resource  specification  into  a  resource  database. 

Synopsis 

void  XrmPutResource ( database,  specifier,  type,  value) 

XrmDatabase  * database;  /*  SEND,  and  if  NULL,  RETURN  */ 
char  * specifier; 
char  *type; 
XrmValue  *  value; 

Arguments 

database         Specifies  a  pointer  to  the  resource  database.  If  database  contains  NULL,  a  new 
resource  database  is  created  and  a  pointer  to  it  is  returned  in  database. 

sped  fier       Specifies  a  complete  or  partial  specification  of  the  resource. 
type  Specifies  the  type  of  the  resource. 

value  Specifies  the  value  of  the  resource. 

Description 

XrmPutResource  is  one  of  several  functions  which  store  data  into  a  database. 

XrmQPutResource  first  converts  specifier  into  a  binding  list  and  a  quark  list  by  calling 
XrmStringToBindingQuarkList,  and  converts  type  into  an  XrmRepresentation 
by  calling  XrmStringToRepresentation.  Finally,  it  puts  the  data  into  the  database. 

XrmPutResource,  XrmQPutResource,  XrmPutStringResource,  XrmQPut- 
StringResource  and  XrmPutLineResource  all  store  data  into  a  database.  See  the 
description  of  XrmQPutResource  for  the  most  complete  description  of  this  process. 

For  more  information,  see  Volume  One,  Chapter  II,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

typedef  struct  { 

unsigned  int     size; 

caddr_t         addr; 
}  XrmValue,  *XrmValuePtr; 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource,  XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource,  XrmPutStringResource,  Xrm- 
QGetResource, XrmQGetSearchList, XrmQGetSearchResource, XrmQPut 
Resource,  XrmQPutStringResource, XrmQuarkToString,  XrmString 
ToBindingQuarkList,  XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 
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-X,,b-  Resource  Manager '  XrmPutStringResource 

Name 

XrmPutStringResource  —  add  a  resource  specification  with  separate  resource  name  and  value. 

Synopsis 

void  XrmPutStringResource (database,  resource,  ^alue) 

XrmDatabase  * database;  /*  SEND,  and  if  NULL,  RETURN  */ 
char  * resource; 
char  * value; 

Arguments 

database          Specifies  a  pointer  to  the  resource  database.  If  database  contains  NULL,  a 
new  resource  database  is  created  and  a  pointer  to  it  is  returned  in  database. 

resource          Specifies  the  resource,  as  a  string. 

val  ue  Specifies  the  value  of  the  resource,  as  a  string. 

Description 

XrmPutStringResource  adds  a  resource  specification  with  the  specified  resource  and 
value  to  the  specified  database.  The  resource  string  may  contain  both  names  and  classes, 
bound  with  either  loose  (*)  or  tight  (.)  bindings.  See  the  description  of  XrmGetResource  for 
more  information  about  bindings. 

The  representation  type  used  in  the  database  is  String. 

XrmPutResource,  XrmQPutResource,  XrmPutStringResource,  XrmQPut- 
StringResource  and  XrmPutLineResource  all  store  data  into  a  database.  See  Xrm 
QPutResource  for  the  most  complete  description  of  this  process. 

For  more  information,  see  Volume  One,  Chapter  II,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases,  XrmParseCommand, 
XrmPutFileDatabase,  XrmPutLineResource, XrmPutResource, XrmQGet- 
Resource, XrmQGetSearchList, XrmQGetSearchResource,  XrmQPutResource, 
XrmQPutStringRe source, XrmQuarkToString,  XrmStringToBindingQuark- 
List,  XrmStringToQuarkList,  XrmStringToQuark, XrmUniqueQuark. 
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XrmQGetResource 

•Xllb  -  Resource  Manager— 

Name 

XrmQGetResource  —  get  a  resource  value  using  name  and  class  as  quarks. 

Synopsis 

Bool  XrmQGetResource (database,  quark_name,  quark_class, 

quark_type,  value) 
XrmDatabase  database; 
XrmNameList  quark_name ; 
XrmClassList  quark_class ; 

XrmRepresentation  *quark_type;  /*  RETURN  */ 
XrmValue  *  value;  /*  RETURN  */ 

Arguments 

da  t  abase          Specifies  the  database  that  is  to  be  used. 

quark_name     Specifies  the  fully  qualified  name  of  the  value  being  retrieved  (as  a  list  of 
quarks). 

quark_class  Specifies  the  fully  qualified  class  of  the  value  being  retrieved  (as  a  list  of 
quarks). 

quark_type     Returns  a  pointer  to  the  representation  type  of  the  value.  In  this  function,  the 
representation  type  is  represented  as  a  quark. 

value  Returns  a  pointer  to  the  value  in  the  database.   Do  not  modify  or  free  this 

data. 

Description 

XrmQGetResource  retrieves  a  resource  from  the  specified  database.  It  takes  fully  qualified 
name  and  class  strings,  and  returns  the  representation  and  value  of  the  matching  resource.  The 
value  returned  points  into  database  memory;  you  must  not  modify  that  data.  If  a  resource  was 
found,  XrmQGetResource  returns  True.  Otherwise,  it  returns  False. 

Currently,  the  database  only  frees  or  overwrites  entries  when  new  data  is  stored  with  Xrm- 
MergeDatabases,  or  XrmPutResource  and  related  routines.  A  client  that  avoids  these 
functions  should  be  safe  using  the  address  passed  back  at  any  time  until  it  exits. 

XrmQGetResource  is  very  similar  to  XrmGetResource,  except  that  in  XrmGet- 
Resource,  the  equivalent  arguments  to  quark_name,  quark_class,  and  quark_type 
arguments  are  strings  instead  of  quarks. 

See  XrmGetResource  for  a  full  description  of  how  data  is  looked  up  in  the  database. 
For  more  information,  see  Volume  One,  Chapter  II,  Managing  User  Preferences. 
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Xlib  -  Resource  Manager  (continued)  XrmQGetResource 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

typedef  XrmQuarkList  XrmNameList; 
typedef  XrmQuarkList  XrmClassList; 
typedef  XrmQuark     XrmRepresentation; 

typedef  struct  { 

unsigned  int     size; 

caddr_t         addr; 
}  XrmValue,  *XrmValuePtr; 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGet Re source, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetSearchList,  XrmQGetSearchResource, XrmQPut- 
Resource, XrmQPutStringResource, XrmQuarkToString, XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 
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XrmQGetSearch  List  "\ 

> Xllb  -  Resource  Manager — 

Name 

XrmQGetSearchList  —  return  a  list  of  database  levels. 

Synopsis 

Bool  XrmQGetSearchList ( database,  names,  classes, 

search_list,  list_length) 
XrmDatabase  database; 
XrmNameList  names; 
XrmClassList  classes; 

XrmSearchList  search_list;  /*  RETURN  */ 
int  list_length; 

Arguments 

database         Specifies  the  database  to  be  searched. 

names  Specifies  a  list  of  resource  names. 

classes  Specifies  a  list  of  resource  classes. 

search_list  Returns  a  search  list  for  further  use.  The  caller  must  allocate  sufficient  space 
for  the  list  before  calling  XrmQGetSearchList. 

list_length  Specifies    the    number    of   entries    (not    the    byte    size)    allocated    for 

search_list. 

Description 

XrmQGetSearchList  is  a  tool  for  searching  the  database  more  efficiently.  It  is  used  in 
combination  with  XrmQGetSearchResource.  Often,  one  searches  the  database  for  many 
similar  resources  which  differ  only  in  their  final  component  (e.g.,  xmh.toc .  foreground, 
xmh .toe .background,  etc).  Rather  than  looking  for  each  resource  in  its  entirety,  Xrm- 
GetSearchList  searches  the  database  for  the  common  part  of  the  resource  name,  returning 
a  whole  list  of  items  in  the  database  that  match  it.  This  list  is  called  the  search  list.  This  search 
list  is  then  used  by  XrmQGetSearchList,  which  searches  for  the  last  components  one  at  a 
time.  In  this  way,  the  common  work  of  searching  for  similar  resources  is  done  only  once,  and 
the  specific  part  of  the  search  is  done  on  the  much  shorter  search  list. 

XrmQGetSearchList  takes  a  list  of  names  and  classes  and  returns  a  list  of  database  levels 
where  a  match  might  occur.  The  returned  list  is  in  best-to-worst  order  and  uses  the  same  algo 
rithm  as  XrmGetResource  for  determining  precedence.  If  search_list  was  large 
enough  for  the  search  list,  XrmQGetSearchList  returns  True.  Otherwise,  it  returns 
False. 

The  size  of  the  search  list  that  must  be  allocated  by  the  caller  is  dependent  upon  the  number  of 
levels  and  wildcards  in  the  resource  specifiers  that  are  stored  in  the  database.  The  worst  case 
length  is  3  n  ,  where  n  is  the  number  of  name  or  class  components  in  names  or  classes. 

Only  the  common  prefix  of  a  resource  name  should  be  specified  in  the  name  and  class  list  to 
XrmQGetSearchList.  In  the  example  above,  the  common  prefix  would  be  xmh.toc. 
However,  note  that  XrmQGetSearchResource  requires  that  name  represent  a  single 
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component  only.  Therefore,  the  common  prefix  must  be  all  but  the  last  component  of  the  name 
and  class. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

typedef  XrmQuarkList  XrmNameList ; 
typedef  XrmQuarkList  XrmClassList ; 
typedef  XrmQuark     XrmRepresentation; 

XrmSearchList  is  a  pointer  to  an  opaque  data  type. 
Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResour.ee,  XrmQGetResource,  XrmQGetSearchResource,  XrmQPut- 
Resource,  XrmQPutStringResource, XrmQuarkToString, XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 
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Name 

XrmQGetSearchResource  —  search  prepared  list  for  a  given  resource. 

Synopsis 

Bool  XrmQGetSearchResource ( search_list,  name,  class, 

type,  value) 

XrmSearchList  search_list ; 
XrmName  name ; 
XrmClass  class; 

XrmRepresentation  *type;  /*  RETURN  */ 
XrmValue  *  value;         /*  RETURN  */ 

Arguments 

search_list  Specifies  the  search  list  returned  by  XrmQGetSearchList. 

name  Specifies  the  resource  name. 

class  Specifies  the  resource  class. 

type  Returns  the  data  representation  type. 

value  Returns  the  value  from  the  database. 

Description 

XrmQGetSearchResource  is  a  tool  for  searching  the  database  more  efficiently.  It  is  used 
in  combination  with  XrmQGetSearchList.  Often,  one  searches  the  database  for  many  simi 
lar  resources  which  differ  only  in  their  final  component  (e.g.,  xmh.  toe .  foreground, 
xmh.  toe  .background,  etc).  Rather  than  looking  for  each  resource  in  its  entirety,  Xrm 
QGetSearchList  searches  the  database  for  the  common  part  of  the  resource  name,  returning 
a  whole  list  of  items  in  the  database  that  match  it.  This  list  is  called  the  search  list.  Xrm 
QGetSearchResource  searches  the  search  list  for  the  resource  that  is  fully  identified  by 
name  and  class.  The  search  stops  with  the  first  match.  XrmQGetSearchResource 
returns  True  if  the  resource  was  found;  otherwise,  it  returns  False. 

A  call  to  XrmQGetSearchList  with  a  name  and  class  list  containing  all  but  the  last  compo 
nent  of  a  resource  name  followed  by  a  call  to  XrmQGetSearchResource  with  the  last  com 
ponent  name  and  class  returns  the  same  database  entry  as  XrmQGet  Re  source  or  XrmQGet- 
Re source  would  with  the  fully  qualified  name  and  class. 

For  more  information,  see  Volume  One,  Chapter  1 1,  Managing  User  Preferences. 
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Structures 

XrmDat abase  is  a  pointer  to  an  opaque  data  type. 

typedef  XrmQuark  XrmName; 

typedef  XrmQuark  XrmClass; 

typedef  XrmQuark  XrmRepresentation; 

typedef  struct  { 

unsigned  int     size; 

caddr_t         addr; 
}  XrmValue,  *XrmValuePtr; 

XrmSearchList  is  a  pointer  to  an  opaque  data  type. 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase,  XrmGetResource,  XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQPutResource, 
XrmQPutStringResource, XrmQuarkToString,  XrmStringToBindingQuark- 
List, XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 
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Name 

XrmQPutResource  —  store  a  resource  specification  into  a  database  using  quarks. 

Synopsis 

void  XrmQPutResource (database,  bindings,  quarks,  type,  value) 
XrmDatabase  *database;   /*  SEND,  and  if  NULL,  RETURN  */ 
XrmBindingList  bindings; 
XrmQuarkList  quarks; 
XrmRepresentation  type; 
XrmValue  *  value; 

Arguments 

database      Specifies  a  pointer  to  the  resource  database.  If  database  contains  NULL,  a  new 
resource  database  is  created  and  a  pointer  to  it  is  returned  in  database. 

bindings  Specifies  a  list  of  bindings  for  binding  together  the  guards  argument. 

quarks  Specifies  the  complete  or  partial  name  or  class  list  of  the  resource  to  be  stored, 

type  Specifies  the  type  of  the  resource. 

val  ue  Specifies  the  value  of  the  resource. 

Description 

XrmQPutResource  stores  a  resource  specification  into  the  database. 

database  can  be  a  previously  defined  database,  as  returned  by  XrmGetStringDatabase, 
XrmGetFileDatabase,  or  from  XrmMergeDatabases.  If  database  is  NULL,  a  new 
database  is  created  and  a  pointer  to  it  returned  in  database. 

bindings  and  quarks  together  specify  where  the  value  should  be  stored  in  the  database. 
See  XrmStringToBindingQuarkList  for  a  brief  description  of  binding  and  quark  lists. 
See  XrmGetResource  for  a  description  of  the  resource  manager  naming  conventions  and 
lookup  rules. 

type  is  the  representation  type  of  value.  This  provides  a  way  to  distinguish  between  differ 
ent  representations  of  the  same  information.  Representation  types  are  user  defined  character 
strings  describing  the  way  the  data  is  represented.  For  example,  a  color  may  be  specified  by  a 
color  name  ("red"),  or  be  coded  in  a  hexadecimal  string  ("#4f6c84")  (if  it  is  to  be  used  as  an 
argument  to  XParseColor.)  The  representation  type  would  distinguish  between  these  two. 
Representation  types  are  created  from  simple  character  strings  by  using  the  macro  Xrm- 
StringToRepresentation.  The  type  XrmRepresentation  is  actually  the  same  type 
as  XrmQuark,  since  it  is  an  ID  for  a  string.  The  representation  is  stored  along  with  the  value 
in  the  database,  and  is  returned  when  the  database  is  accessed. 

value  returns  the  value  of  the  resource,  specified  as  an  XrmValue. 

XrmGetResource  contains  the  complete  description  of  how  data  is  accessed  from  the  data 
base,  and  so  provides  a  good  perspective  on  how  it  is  stored. 
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For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

typedef   enum    { 

XrmBindTightly,    XrmBindLoosely 
}    XrmBinding,    *XrmBindingList ; 

typedef    int    XrmQuark,     *XrmQuarkList; 
typedef   XrmQuarkList   XrmNameList; 
typedef   XrmQuark   XrmRepresentation; 

typedef   struct    { 

unsigned   int    size; 

caddr_t   addr; 
}    XrmValue,    *XrmValuePtr; 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource,  XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDat abases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource,  XrmPutResource,  XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch- 
Resource, XrmQPutStringResource,  XrmQuarkToString,  XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark, Xrm- 
UniqueQuark. 
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Name 

XrmQPutStringResource  —  add  a  resource  specification  to  a  database  using  a  quark  resource 
name  and  string  value. 

Synopsis 

void  XrmQPutStringResource ( database,  bindings,  quarks,  value) 
XrmDatabase  *database;  /*  SEND,  and  if  NULL,  RETURN  */ 
XrmBindingList  bindings; 
XrmQuarkList  quarks; 
char  *  value; 

Arguments 

database      Specifies  a  pointer  to  the  resource  database.  If  database  contains  NULL,  a  new 
resource  database  is  created  and  a  pointer  to  it  is  returned  in  database. 

bindings       Specifies  a  list  of  bindings  for  binding  together  the  guards  argument. 
guards  Specifies  the  complete  or  partial  name  or  class  list  of  the  resource  to  be  stored. 

val  ue  Specifies  the  value  of  the  resource  as  a  string. 

Description 

XrmQPutStringResource  stores  a  resource  specification  into  the  specified  database. 

XrmQPutStringResource  is  a  cross  between  XrmQPutResource  and  XrmPut- 
StringResource.  Like  XrmQPutResource,  it  specifies  the  resource  by  guards  and 
bindings,  two  lists  that  together  make  a  name/class  list  with  loose  and  tight  bindings.  Like 
XrmPutStringResource,  it  specifies  the  value  to  be  stored  as  a  string,  that  value  is  con 
verted  into  an  XrmValue,  and  the  default  representation  type  String  is  used. 

XrmPutResource,  XrmQPutResource,  XrmPutStringResource,  XrmQPut 
StringResource  and  XrmPutLineResource  all  store  data  into  a  database.  See  Xrm 
QPutResource  for  the  most  complete  description  of  this  process. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 

Structures 

XrmDatabase  is  a  pointer  to  an  opaque  data  type. 

typedef  enum  { 

XrmBindTightly,  XrmBindLoosely 
}  XrmBinding,  *XrmBindingList ; 

typedef  int  XrmQuark,  *XrmQuarkList ; 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource,  XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource,  XrmPut 
StringResource,  XrmQGetResource, XrmQGetSearchList, XrmQGetSearch- 
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Resource, XrmQPutResource,  XrmQuarkToString,  XrmStringToBinding- 
QuarkList,  XrmStringToQuarkList,  XrmStringToQuark,  XrmUniqueQuark. 


Xlib  Reference  Manual  405 


XrmQuarkToString  \ X||b  _  Resource  Managar_ 

Name 

XrmQuarkToString  —  convert  a  quark  to  a  string. 

Synopsis 

char  *XrmQuarkToString ( quark) 
XrmQuark  quark; 

Arguments 

quark  Specifies  the  quark  for  which  the  equivalent  string  is  desired. 

Description 

XrmQuarkToString  returns  the  string  for  which  the  specified  quark  is  serving  as  a  short 
hand  symbol.  The  quark  was  earlier  set  to  represent  the  string  by  XrmStringToQuark.  The 
string  pointed  to  by  the  return  value  must  not  be  modified  or  freed,  because  that  string  is  in  the 
data  structure  used  by  the  resource  manager  for  assigning  quarks.  If  no  string  exists  for  that 
quark,  XrmQuarkToString  returns  NULL. 

Since  the  resource  manager  needs  to  make  many  comparisons  of  strings  when  it  gets  data  from 
the  database,  it  is  more  efficient  to  convert  these  strings  into  quarks,  and  to  compare  quarks 
instead.  Since  quarks  are  represented  by  integers,  comparing  quarks  is  trivial. 

The  three  #def  ine  statements  in  the  Structures  section  provide  an  extra  level  of  abstraction. 
They  define  macros  so  that  names,  classes  and  representations  can  also  be  represented  as 
quarks. 

For  more  information,  see  Volume  One,  Chapter  II,  Managing  User  Preferences. 
Structures 

typedef    int   XrmQuark; 

/*   macro   definitions    from   <Xll/Xresource ,h>    */ 

#define    XrmNameToString (name)    XrmQuarkToString (name) 
#define   XrmClassToString (class)    XrmQuarkToString (class) 
#define   XrmRepresentationToString (type)    XrmQuarkToString (type) 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize,  XrmMergeDatabases,  XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList,  XrmQGetSearch- 
Resource, XrmQPutResource, XrmQPutStringResource, XrmString- 
ToBindingQuarkList, XrmStringToQuarkList, XrmStringToQuark,  Xrm- 
UniqueQuark. 
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J       XrmStringToBindingQuarkList 


Name 

XrmStringToBindingQuarkList  —  convert  a  key  string  to  a  binding  list  and  a  quark  list. 
Synopsis 

XrmStringToBindingQuarkList (string,  bindings,  quarks) 
char  *string; 

XrmBindingList  bindings;  /*  RETURN  */ 
XrmQuarkList  quarks;      /*  RETURN  */ 

Arguments 

string  Specifies  the  string  for  which  the  list  of  quarks  and  list  of  bindings  are  to  be 

generated.  Must  be  NULL  terminated. 

bindings         Returns  the  binding  list.   The  caller  must  allocate  sufficient  space  for  the 
binding  list  before  the  call. 

quark  Returns  the  list  of  quarks.  The  caller  must  allocate  sufficient  space  for  the 

quarks  list  before  the  call. 

Description 

XrmStringToBindingQuarkList  converts  a  resource  specification  string  into  two  lists — 
one  of  quarks  and  one  of  bindings.  Component  names  in  the  list  are  separated  by  a  dot  (".") 
indicating  a  tight  binding  or  an  asterisk  ("*")  indicating  a  loose  binding.  If  the  string  does  not 
start  with  dot  or  asterisk,  a  dot  (".")  is  assumed. 

A  tight  binding  means  that  the  quarks  on  either  side  of  the  binding  are  consecutive  in  the  key. 
A  loose  binding,  on  the  other  hand,  is  a  wildcard  that  can  match  any  number  of  unspecified 
components  in  between  the  two  quarks  separated  by  the  binding.  Tight  and  loose  bindings  are 
used  in  the  match  rules,  which  compare  multicomponent  strings  to  find  matches  and  determine 
the  best  match.  See  XrmGet  Re  source  for  a  full  description  of  lookup  rules. 

For  example,  *a .  b*c  becomes: 

quarks      bindings 

"a"  XrmBindLoosely 
"b"  XrmBindTightly 
"c"  XrmBindLoosely 

For  more  information,  see  Volume  One,  Chapter  II,  Managing  User  Preferences. 
Structures 

typedef  int  XrmQuark,  *XrmQuarkList ; 
typedef  enum  ( 

XrmBindLoosely,  XrmBindTightly 
)  XrmBinding,  *XrmBindingList ; 
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Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource,  XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList,  XrmQGetSearch- 
Resource, XrmQPutResource,  XrmQPutStringResource,  XrmQuarkToString, 
XrmStringToQuarkList, XrmStringToQuark, XrmUniqueQuark. 
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J  XrmStringToQuark 


Name 

XrmStringToQuark  —  convert  a  string  to  a  quark. 

Synopsis 

XrmQuark  XrmStringToQuark (string) 
char  *string; 

Arguments 

string  Specifies  the  string  for  which  a  quark  is  to  be  allocated. 

Description 

XrmStringToQuark  returns  a  quark  that  will  represent  the  specified  string.  If  a  quark 
already  exists  for  the  string,  that  previously  existing  quark  is  returned.  If  no  quark  exists  for  the 
string,  then  a  new  quark  is  created,  assigned  to  the  string,  and  string  is  copied  into  the  quark 
table.  (Since  string  is  copied,  it  may  be  freed.  However,  the  copy  of  the  string  in  the  quark 
table  must  not  be  modified  or  freed.)  XrmQuarkToString  performs  the  inverse  function. 

Since  the  resource  manager  needs  to  make  many  comparisons  of  strings  when  it  gets  data  from 
the  database,  it  is  more  efficient  to  convert  these  strings  into  quarks,  and  to  compare  quarks 
instead.  Since  quarks  are  presently  represented  by  integers,  comparing  quarks  is  trivial. 

The  three  #def  ine  statements  in  the  Structures  section  provide  an  extra  level  of  abstraction. 
They  define  macros  so  that  names,  classes,  and  representations  can  also  be  represented  as 
quarks. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 
Structures 

typedef  int  XrmQuark; 

/*  macro  definitions  from  <Xll/Xresource ,h>  */ 

tdefine  XrmStringToName (string)  XrmStringToQuark (string) 

#define  XrmStringToClass (string)  XrmStringToQuark (string) 

#def ine  XrmStringToRepresentation (string)  XrmStringToQuark (string) 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource,  XrmGet- 
StringDatabase, Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch- 
Resource,  XrmQPutResource, XrmQPutStringResource, XrmQuarkToString, 
XrmStringToBindingQuarkList, XrmStringToQuarkList,  XrmUniqueQuark. 
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Name 

XrmStringToQuarkList  —  convert  a  key  string  to  a  quark  list. 

Synopsis 

void  XrmStringToQuarkList ( string,  quarks) 
char  *string; 
XrmQuarkList  quarks;      /*  RETURN  */ 

Arguments 

string  Specifies  the  string  for  which  a  list  of  quarks  is  to  be  generated.  Must  be  null- 

terminated.    The  components  may  be  separated  by  the  "."  character  (tight 
binding)  or  the  "*"  character  (loose  binding). 

quarks  Returns  the  list  of  quarks. 

Description 

XrmStringToQuarkList  converts  string  (generally  a  fully  qualified  name/class  string) 
to  a  list  of  quarks.  Components  of  the  string  may  be  separated  by  a  tight  binding  (the  "."  char 
acter)  or  a  loose  binding  ("*").  Use  XrmStringToBindingQuarkList  for  lists  which 
contain  both  tight  and  loose  bindings.  See  XrmGetResource  for  a  description  of  tight  and 
loose  binding. 

Each  component  of  the  string  is  individually  converted  into  a  quark.  See  XrmString- 
ToQuark  for  information  about  quarks  and  converting  strings  to  quarks,  quarks  is  a  null- 
terminated  list  of  quarks. 

For  example,  xmh .  toe  .  command .  background  is  converted  into  a  list  of  four  quarks:  the 
quarks  for  xmh,  toe,  command,  and  background,  in  that  order.  A  NULLQUARK  is  appended 
to  the  end  of  the  list. 

Note  that  XrmStringToNameList  and  XrmStringToClassList  are  macros  that  per 
form  exactly  the  same  function  as  XrmStringToQuarkList.  These  may  be  used  in  cases 
where  they  clarify  the  code. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 
Structures 

typedef  int  XrmQuark  *XrmQuarkList; 

#define  XrmStringToNameList (str,  name)   XrmStringToQuarkList ( (str) ,  (name)) 
tdefine  XrmStringToClassList (str, class)  XrmStringToQuarkList ( (str) ,  (class)) 
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Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGetStringDatabase, 
Xrmlnitialize, XrmMergeDatabases, XrmParseCommand, XrmPutFileDatabase, Xrm- 
PutLineResource, XrmPutResource, XrmPutStringResource, XrmQGetResource, Xrm- 
QGetSearchList, XrmQGetSearchResource, XrmQPutResource, XrmQPutString- 
Resource,  XrmQuarkToString, XrmStringToBindingQuarkList, XrmStringToQuark, 
XrmStringToRepresentation.XrmUniqueQuark. 
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v Xlib  -  Resource  Manager- 
Name 

XrmUniqueQuark  —  allocate  a  new  quark. 

Synopsis 

XrmQuark  XrmUniqueQuark (  ) 

Description 

XrmUniqueQuark  allocates  a  quark  that  is  guaranteed  not  to  represent  any  existing  string. 
For  most  applications,  XrmStringToQuark  is  more  useful,  as  it  binds  a  quark  to  a  string. 
However,  on  some  occasions,  you  may  want  to  allocate  a  quark  that  has  no  string  equivalent. 

The  shorthand  name  for  a  string  is  called  a  quark  and  is  the  type  XrmQuark.  Quarks  are  used 
to  improve  performance  of  the  resource  manager,  which  must  make  many  string  comparisons. 
Quarks  are  presently  represented  as  integers.  Simple  comparisons  of  quarks  can  be  performed 
rather  than  lengthy  string  comparisons. 

A  quark  is  to  a  string  what  an  atom  is  to  a  property  name  in  the  server,  but  its  use  is  entirely 
local  to  your  application. 

For  more  information,  see  Volume  One,  Chapter  11,  Managing  User  Preferences. 
Structures 

typedef  int  XrmQuark; 

Related  Commands 

XrmDestroyDatabase, XrmGetFileDatabase, XrmGetResource, XrmGet- 
StringDatabase, Xrmlnitialize,  XrmMergeDatabases,  XrmParseCommand, 
XrmPutFileDatabase, XrmPutLineResource, XrmPutResource, XrmPut- 
StringResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearch- 
Resource, XrmQPutResource,  XrmQPutStringResource,  XrmQuarkToString, 
XrmStringToBindingQuarkList, XrmStringToQuarkList,  XrmStringTo 
Quark. 
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D  „    J  XRotateBuffers 

— Xlib  -  Cut  Buffers ' 

Name 

XRotateBuffers  —  rotate  the  cut  buffers. 

Synopsis 

XRotateBuffers (display,  rotate) 
Display  * display; 
int  rotate; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

rotate  Specifies  how  many  positions  to  rotate  the  cut  buffers. 

Description 

XRotateBuffers  rotates  the  8  cut  buffers  the  amount  specified  by  rotate.  The  contents 

of  buffer  0  moves  to  buffer  rotate,  contents  of  buffer  1  moves  to  buffer  (rotate+1)  mod  8, 

contents  of  buffer  2  moves  to  buffer  (rotate+2)  mod  8,  and  so  on. 

This  routine  will  not  work  if  any  of  the  buffers  have  not  been  stored  into  with  xstoreBuf  f  er 

orXStoreBytes. 

This  cut  buffer  numbering  is  global  to  the  display. 

See  the  description  of  cut  buffers  in  Volume  One,  Chapter  13,  Other  Programming  Techniques. 

Related  Commands 

XFetchBuf f er, XFetchBytes, XStoreBuf f er, XStoreBytes. 
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XRotateWindowProperties 


X 


Xlib- Properties- 


Name 

XRotateWindowProperties  —  rotate  properties  in  the  properties  array. 


properties,    num_jprop, 


Synopsis 

XRotateWindowProperties  ( display, 

npositions) 
Display  * display; 
Window  w; 

Atom  properties  [] ; 
int  num_prop; 
int  npositions; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  whose  properties  are  to  be  rearranged. 

properties     Specifies  the  list  of  properties  to  be  rotated. 
num_prop         Specifies  the  length  of  the  properties  array. 

npositions     Specifies  the  number  of  positions  to  rotate  the  property  list.  The  sign  controls 
the  direction  of  rotation. 

Description 

XRotateWindowProperties  rotates  the  contents  of  an  array  of  properties  on  a  window.  If 
the  property  names  in  the  properties  array  are  viewed  as  if  they  were  numbered  starting 
from  0  and  if  there  are  num_prop  property  names  in  the  list,  then  the  value  associated  with 
property  name  /  becomes  the  value  associated  with  property  name  (/  +  npositions)  mod 
num_prop,  for  all  /  from  0  to  num_prop  -  1.  Therefore,  the  sign  of  npositions  controls 
the  direction  of  rotation.  The  effect  is  to  rotate  the  states  by  npositions  places  around  the 
virtual  ring  of  property  names  (right  for  positive  npositions,  left  for  negative  nposi- 
tion). 

If  npositions  mod  num_j>rop  is  nonzero,  a  PropertyNotify  event  is  generated  for 
each  property,  in  the  order  listed. 

If  a  BadAtom,  BadMatch,  or  Badwindow  error  is  generated,  no  properties  are  changed. 


Error 

BadAtom 

BadMatch 
Badwindow 


Atom  occurs  more  than  once  in  list  for  the  window. 
No  property  with  that  name  for  the  window. 

An  atom  appears  more  that  once  in  the  list  or  no  property  with  that  name  is 
defined  for  the  window. 


414 
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Xlib  -  Properties  (continued)  XRotateWindOWPrOpertieS 

Related  Commands 

XChangeProperty, XDeleteProperty, XGetAtomName,  XGetFontProperty, 
XGetWindowProperty, XInternAtom,  XListProperties,  XSetStandard- 
Properties. 
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XSaveContext  \ Vll 

N Xlib  -  Context  Manager — 

Name 

XSaveContext  —  save  a  data  value  corresponding  to  a  window  and  context  type  (not  graphics 
context). 

Synopsis 

int  XSaveContext ( display,  w,  context,  data) 
Display  *  display; 
Window  w; 
XContext  context; 
caddr_t  data; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

w  Specifies  the  ID  of  the  window  with  which  the  data  is  associated. 

context  Specifies  the  context  type  to  which  the  data  corresponds. 

data  Specifies  the  data  to  be  associated  with  the  window  and  context. 

Description 

XSaveContext  saves  data  to  the  context  manager  database,  according  to  the  specified  win 
dow  and  context  ID.  The  context  manager  is  used  for  associating  data  with  windows  within 
an  application.  The  client  must  have  called  XUniqueContext  to  get  the  context  ID 
before  calling  this  function.  The  meaning  of  the  data  is  indicated  by  the  context  ID,  but  is 
completely  up  to  the  client. 

If  an  entry  with  the  specified  window  and  context  ID  already  exists,  XSaveContext  writes 
over  it  with  the  specified  data. 

The  XSaveContext  function  returns  XCNOMEM  (a  nonzero  error  code)  if  an  error  has  occurred 
and  zero  (0)  otherwise.  For  more  information,  see  the  description  of  the  context  manager  in 
Volume  One,  Chapter  13,  Other  Programming  Techniques. 

Structures 

typedef   int   XContext; 

Related  Commands 

XDeleteContext, XFindContext, XUniqueContext. 
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-X,,b  -  ,npu,  Hand,,ng 


Name 

XSelectlnput  —  select  the  event  types  to  be  sent  to  a  window. 

Synopsis 

XSelectlnput  (display,  w,  event_mask) 
Display  *  display  ; 
Window  w; 
long  event_mask; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

w  Specifies  the  ID  of  the  window  interested  in  the  events. 

event_mask     Specifies  the  event  mask.  This  mask  is  the  bitwise  OR  of  one  or  more  of  the 
valid  event  mask  bits  (see  below). 

Description 

XSelectlnput  defines  which  input  events  the  window  is  interested  in.  If  a  window  is  not 
interested  in  a  device  event  (button,  key,  motion,  or  border  crossing),  it  propagates  up  to  the 
closest  ancestor  unless  otherwise  specified  in  the  do_not_propagate_mask  attribute. 

The  bits  of  the  mask  are  defined  in  <Xll/X.h>  : 

ButtonPressMask  NoEventMask 

ButtonReleaseMask  KeyPressMask 

EnterWindowMask  KeyReleaseMask 

LeaveWindowMask  ExposureMask 

Point  erMotionMask  VisibilityChangeMask 
PointerMotionHintMask     StructureNotifyMask 

ButtonlMotionMask  ResizeRedirectMask 

Button2MotionMask  SubstructureNotifyMask 

ButtonSMotionMask  SubstructureRedirectMask 

Button4MotionMask  FocusChangeMask 

ButtonSMotionMask  PropertyChangeMask 

ButtonMotionMask  ColormapChangeMask 

KeymapStateMask  OwnerGrabButtonMask 

A  call  on  XSelectlnput  overrides  any  previous  call  on  XSelectlnput  for  the  same  win 
dow  from  the  same  client  but  not  for  other  clients.  Multiple  clients  can  select  input  on  the  same 
window;  their  event_mask  window  attributes  are  disjoint.  When  an  event  is  generated  it  will 
be  reported  to  all  interested  clients.  However,  only  one  client  at  a  time  can  select  for  each  of 
SubstructureRedirectMask,  ResizeRedirectMask,  and  ButtonPress. 

If  a  window  has  both  ButtonPressMask  and  ButtonReleaseMask  selected,  then  a 
ButtonPress  event  in  that  window  will  automatically  grab  the  mouse  until  all  buttons  are 
released,  with  events  sent  to  windows  as  described  for  XGrabPointer.  This  ensures  that  a 
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XSeleCtlnpUt  (continued)  Xlib  -  Input  Handling 

window  will  see  the  ButtonRelease  event  corresponding  to  the  ButtonPress  event, 
even  though  the  mouse  may  have  exited  the  window  in  the  meantime. 

If  PointerMotionMask  is  selected,  events  will  be  sent  independent  of  the  state  of  the 
mouse  buttons.  If  instead,  one  or  more  of  ButtonlMotionMask,  Button2MotionMask, 
Button3MotionMask,  Button4MotionMask,  ButtonSMotionMask  is  selected, 
MotionNotif  y  events  will  be  generated  only  when  one  or  more  of  the  specified  buttons  is 
depressed. 

XCreateWindow  and  XChangeWindowAt tributes  can  also  set  the  event_mask  attri 
bute. 

For  more  information,  see  Volume  One,  Chapter  8,  Events. 

Errors 

Badva  lue          Specified  event  mask  invalid. 

BadWindow 

Related  Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent,  XCheckTyped- 
Event,  XCheckTypedWindowEvent, XCheckWindowEvent,  XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent, XNextEvent, 
XPeekEvent, XPeeklf Event, XPending,  XPutBackEvent,  XSendEvent,  XSet- 
InputFocus, XSynchronize, XWindowEvent. 
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-xiib  -  input  Handling /  XSendEvent 

Name 

XSendEvent  —  send  an  event 

Synopsis 

Status  XSendEvent (display,  w,  propagate,  event_maskr  event) 
Display  *display; 
Window  w; 
Bool  propagate; 
long  event_mask / 
XEvent  *event; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XQpenD i  sp  1  ay. 

w  Specifies  the  ID  of  the  window  where  you  want  to  send  the  event  Pass  the 

window  resource  ID,  PointerWindow,  or  InputFocus. 

propagate       Specifies  how  the  sent  event  should  propagate  depending  on  event_mask. 
See  description  below.  May  be  True  or  False. 

event_mask     Specifies  the  event  mask.   See  XSelect Input  for  a  detailed  list  of  the 
event  masks. 

event  Specifies  a  pointer  to  the  event  to  be  sent. 

Errors 

BadValue          Specified  event  is  not  a  valid  core  or  extension  event  type,  or  event  mask  is 
invalid. 

BadWindow 

Description 

XSendEvent  sends  an  event  from  one  client  to  another  (or  conceivably  to  itself).  This  func 
tion  is  used  for  communication  between  clients  using  selections,  for  simulating  user  actions  in 
demos,  and  for  other  purposes. 

The  specified  event  is  sent  to  the  window  indicated  by  w  regardless  of  active  grabs. 

If  w  is  set  to  PointerWindow,  the  destination  of  the  event  will  be  the  window  that  the  pointer 
is  in.  If  w  is  InputFocus  is  specified,  then  the  destination  is  the  focus  window,  regardless  of 
pointer  position. 

If  propagate  is  False,  then  the  event  is  sent  to  every  client  selecting  on  the  window  speci 
fied  by  w  any  of  the  event  types  in  event_mask.  If  propagate  is  True  and  no  clients  have 
been  selected  on  w  any  of  the  event  types  in  event_mask,  then  the  event  propagates  like  any 
other  event. 

The  event  code  must  be  one  of  the  core  events,  or  one  of  the  events  defined  by  a  loaded  exten 
sion,  so  that  the  server  can  correctly  byte  swap  the  contents  as  necessary.  The  contents  of  the 
event  are  otherwise  unaltered  and  unchecked  by  the  server.  The  send_event  field  in  every 
event  type,  which  if  True  indicates  that  the  event  was  sent  with  XSendEvent. 
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XSendEvent  (continued)  Xlib- Input  Handling 

This  function  is  often  used  in  selection  processing.  For  example,  the  owner  of  a  selection 
should  use  XSendEvent  to  send  a  Select  ionNot  if  y  event  to  a  requestor  when  a  selec 
tion  has  been  converted  and  stored  as  a  property.  See  Volume  One,  Chapter  10,  Interclient 
Communication  for  more  information. 

The  status  returned  by  XSendEvent  indicates  whether  or  not  the  given  XEvent  structure  was 
successfully  converted  into  a  wire  event.  This  value  is  zero  on  failure,  or  nonzero  on  success. 
Along  with  changes  in  the  extensions  mechanism,  this  makes  merging  of  two  wire  events  into  a 
single  user-visible  event  possible. 

Structures 

See  Appendix  E,  Event  Reference,  for  the  contents  of  each  event  structure. 

Related  Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event,  XCheckTypedWindowEvent, XCheckWindowEvent,  XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event, XMaskEvent,  XNextEvent, 
XPeekEvent,  XPeeklf Event, XPending,  XPutBackEvent, XSelectlnput, XSet- 
InputFocus, XSynchronize,  XWindowEvent. 
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-x,ib  -  HO*  Acce,, /  XSetAccessControl 

Name 

XSetAccessControl  —  disable  or  enable  access  control. 

Synopsis 

XSetAccessControl (display,  mode) 
Display  * display ; 
int  mode ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

mode  Specifies  whether  you  want  to  enable  or  disable  the  access  control.  Pass  one 

of  these  constants:  EnableAccess  orDisableAccess. 

Description 

XSetAccessControl  specifies  whether  the  server  should  check  the  host  access  list  before 
allowing  access  to  clients  running  on  remote  hosts.  If  the  constant  used  is  DisableAccess, 
clients  from  any  host  have  access  unchallenged. 

This  routine  can  only  be  called  from  a  client  running  on  the  same  host  as  the  server. 

For  more  information  on  access  control  lists,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 

Errors 

BadAccess 
BadValue 

Related  Commands 

XAddHost, XAddHosts,  XDisableAccessControl,  XEnableAccessControl, 
XListHosts, XRemoveHost, XRemoveHosts. 
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XSet  After  Function  "\ VI1 

v Xlib  -  Error  Handling- 
Name 

XSetAfterFunction  —  set  a  function  called  after  all  Xlib  functions. 

Synopsis 

int  (*XSetAfterFunct ion (display,  func))() 
Display  * display; 
int  (*func)  ()  ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

func  Specifies  the  user-defined  function  to  be  called  after  each  Xlib  function.  This 

function  is  called  with  one  argument,  the  display  pointer. 

Description 

All  Xlib  functions  that  generate  protocol  requests  can  call  what  is  known  as  an  after  function 
after  completing  their  work  (normally,  they  don't).  XSetAfterFunction  allows  you  to 
write  a  function  to  be  called. 

XSynchronize  sets  an  after  function  to  make  sure  that  the  input  and  request  buffers  are 
flushed  after  every  Xlib  routine. 

For  more  information,  see  Volume  One,  Chapter  13,  Other  Programming  Techniques. 
Related  Commands 

XDisplayName, XGetErrorDatabaseText, XGetErrorText, XSetError- 
Handler,  XSetlOErrorHandler, XSynchronize. 
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— Xlib  -  Graphics  Context- 


XSetArcMode 


Name 

XSetArcMode  —  set  the  arc  mode  in  a  graphics  context. 

Synopsis 

XSetArcMode  (  display,  gc ,  arc_mode) 
Display  *  display; 
GC  gc; 
int  arc  mode; 


Arguments 

display 

gc 

arc  mode 


Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 
Specifies  the  graphics  context. 

Specifies  the  arc  mode  for  the  specified  graphics  context.  Possible  values  are 
ArcChordorArcPieSli.ee. 


Description 

XSetArcMode  sets  the  arc_mode  component  of  a  GC,  which  controls  filling  in  the  XFill- 
Arcs  function.  ArcChord  specifies  that  the  area  between  the  arc  and  a  line  segment  joining 
the  endpoints  of  the  arc  is  filled.  ArcPieSlice  specifies  that  the  area  filled  is  delimited  by 
the  arc  and  two  line  segments  connecting  the  ends  of  the  arc  to  the  center  point  of  the  rectangle 
defining  the  arc. 


ArcChord 


ArcPieSlice 
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XSetArcMode  (continued)  Xlib  -  Graphics  Context 

Errors 

BadGC 
BadValue 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetBackground, XSetClipMask,  XSetClipOrigin,  XSetClipRectangles, 
XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground,  XSet- 
Function,  XSetGraphicsExposures, XSetLineAttributes,  XSetPlaneMask, 
XSetState, XSetStipple, XSetSubwindowMode,  XSetTSOrigin. 
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— Xlib  -  Graphics  Context- 


J  XSetBackground 


Name 

XSetBackground  —  set  the  background  pixel  value  in  a  graphics  context. 

Synopsis 

XSetBackground  (display,  gc ,  background) 
Display  *  display; 
GC  gc; 
unsigned  long  background; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

gc  Specifies  the  graphics  context. 

background     Specifies  the  background  component  of  the  GC. 

Description 

XSetBackground  sets  the  background  pixel  value  component  of  a  GC.  Note  that  this  is 
different  from  the  background  of  a  window,  which  can  be  set  with  either  XSetwindow- 

Background  or  XSetWindowBackgroundPixmap. 

The  specified  pixel  value  must  be  returned  by  BlackPixel,  WhitePixel,  or  one  of  the  rou 
tines  that  allocate  colors. 

Errors 

BadGC 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode, XSetClipMask, XSetClipOrigin,  XSetClipRectangles, XSet- 
Dashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple,  XSetSubwindowMode,  XSetTSOrigin. 
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XSetClaSSHint  V X,,b- Window  Manager  Hints- 

Name 

XSetClassHint  —  set  the  XA_WM_CLASS  property  of  a  window. 

Synopsis 

XSetClassHint ( display,  w,  class_hints) 
Display  *  display; 
Window  w; 
XClassHint  *class_hints ; 

Arguments 

di spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi  spl ay . 

w  Specifies  the  ID  of  the  window  for  which  the  class  hint  is  to  be  set. 

class_hints  Specifies  the  XClassHint  structure  that  is  to  be  used. 

Description 

XSetClassHint  sets  the  XA_WM_CLASS  property  for  the  specified  window.  The  window 
manager  may  (or  may  not)  read  this  property,  and  use  it  to  get  resource  defaults  that  apply  to 
the  window  manager's  handling  of  this  application. 

The  XClassHint  structure  set  contains  res_class,  which  is  the  name  of  the  client  such  as 
"emacs",  and  res_name,  which  is  the  first  of  the  following  that  applies: 

•  command  line  option  (-rn  name) 

a  specific  environment  variable  (e.g.,  RESOURCE_NAME) 

•  the  trailing  component  of  argv  [  0  ]  (after  the  last  /) 

For  more  information,  see  Volume  One,  Chapter  10, Inter client  Communication. 

Errors 

BadAlloc 
BadWindow 

Structures 

typedef   struct    { 

char    *res_name; 

char    *res_class; 
}    XClassHint; 

Related  Commands 

XAllocClassHint,XFetchName,XGetClassHint,XGetIconName,XGet Icon- 
Sizes,  XGetNormalHints, XGetSizeHints, XGetTransientForHint, XGet- 
WMHints, XGetZoomHints, XSetCommand,  XSet IconName, XSetlconSizes, 
XSetNormalHints, XSetSizeHints, XSetTransientForHint, XSetWMHints, 
XSetZoomHints, XStoreName, XSetWMProperties. 
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-XHb  -  Graphics  Con«,x, '  XSetClipMask 

Name 

XSetClipMask  —  set  clip_mask  pixmap  in  a  graphics  context. 

Synopsis 

XSetClipMask  (display ,  gc,  clip_mask) 
Display  *display; 
GC  gc; 
Pixmap  clip_mask; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

gc  Specifies  the  graphics  context. 

clip_jnas;c       Specifies  a  pixmap  of  depth  1  to  be  used  as  the  clip  mask.  Pass  the  constant 
None  if  no  clipping  is  desired. 

Description 

XSetClipMask  sets  the  clip_mask  component  of  a  GC  to  a  pixmap.  The  clip_mask  fil 
ters  which  pixels  in  the  destination  are  drawn.  If  clip_mask  is  set  to  None,  the  pixels  are 
always  drawn,  regardless  of  the  clip  origin.  Use  XSetClipRectangles  to  set  clip_mask 
to  a  set  of  rectangles,  or  XSetRegion  to  set  clip_mask  to  a  region. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
Errors 

BadGC 

BadMatch 

BadPixmap 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipOrigin,  XSetClipRectangles, 
XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, XSet- 
Function,  XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, 
XSetState, XSetStipple, XSetSubwindowMode,  XSetTSOrigin. 
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XSetClipOrigin  \ X1|b  _  Graph|cs  Contexl_ 

Name 

XSetClipOrigin  —  set  the  clip  origin  in  a  graphics  context. 

Synopsis 

XSetClipOrigin (display,    gc ,    clip_x_origin,    clip_y_origin) 
Display   * display; 
GC   gc; 
int    clip_x_originf    cl ip_y_ origin ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

gc  Specifies  the  graphics  context. 

clip_x_origin  Specify  the  coordinates  of  the  clip  origin  (interpreted  later  relative  to  the 
clip_y_origin  window  drawn  into  with  this  GC). 

Description 

XSetClipOrigin  sets  the  clip_x_origin  and  clip_y_origin  components  of  a  GC. 
The  clip  origin  controls  the  position  of  the  clip_mask  in  the  GC,  which  filters  which  pixels 
are  drawn  in  the  destination  of  a  drawing  request  using  this  GC. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
Errors 

BadGC 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode,  XSetBackground, XSetClipMask,  XSetClipRectangles, XSet- 
Dashes, XSetFillRule, XSetFillStyle,  XSetForeground,  XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask,  XSetState, 
XSetStipple, XSetSubwindowMode,  XSetTSOrigin. 
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— Xlib  -  Graphics  Context - 


J  XSetClipRectangles 


Name 

XSetClipRectangles  —  change  clip_mask  in  a  graphics  context  to  a  list  of  rectangles. 

Synopsis 

XSetClipRectangles (display,  gc ,  clip_x_orlgin, 

clip_y_origin,  rectangles,  nrects ,  ordering) 
Display  * display; 
GC  gc; 

int  clip_x_originr  clip_y_  origin; 
XRectangle  rectangles []  ; 
int  nrects; 
int  ordering; 

Arguments 

di splay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

gc  Specifies  the  graphics  context. 

clip_x_ origin  Specify  the  x  and  y  coordinates  of  the  clip  origin  (interpreted  later  rela- 
clip_y_ origin  live  to  the  window  drawn  into  with  this  GC). 

rectangles  Specifies  an  array  of  rectangles.  These  are  the  rectangles  you  want  draw 

ing  clipped  to. 

nrects  Specifies  the  number  of  rectangles. 

ordering  Specifies  the  ordering  relations  of  the  rectangles.    Possible  values  are 

Unsorted,  YSorted,  YXSorted,  or  YXBanded. 

Description 

XSetClipRectangles  changes  the  clip_mask  component  in  the  specified  GC  to  the 
specified  list  of  rectangles  and  sets  the  clip  origin  to  clip_x_origin  and  clip_y_ori- 
gin.  The  rectangle  coordinates  are  interpreted  relative  to  the  clip  origin.  The  output  from 
drawing  requests  using  that  GC  are  henceforth  clipped  to  remain  contained  within  the  rectan 
gles.  The  rectangles  should  be  nonintersecting,  or  the  graphics  results  will  be  undefined.  If  the 
list  of  rectangles  is  empty,  output  is  effectively  disabled  as  all  space  is  clipped  in  that  GC.  This 
is  the  opposite  of  a  clip_mask  of  None  in  XCreateGC,  XChangeGC,  or  XSetClipMask. 

If  known  by  the  client,  ordering  relations  on  the  rectangles  can  be  specified  with  the  order 
ing  argument  This  may  provide  faster  operation  by  the  server.  If  an  incorrect  ordering  is 
specified,  the  X  server  may  generate  a  BadMatch  error,  but  it  is  not  required  to  do  so.  If  no 
error  is  generated,  the  graphics  results  are  undefined.  Unsorted  means  the  rectangles  are  in 
arbitrary  order.  YSorted  means  that  the  rectangles  are  nondecreasing  in  their  y  origin. 
YXSorted  additionally  constrains  YSorted  order  in  that  all  rectangles  with  an  equal  y  origin 
are  nondecreasing  in  their  x  origin.  YXBanded  additionally  constrains  YXSorted  by  requir 
ing  that,  for  every  possible  horizontal  y  scan  line,  all  rectangles  that  include  that  scan  line  have 
identical  y  origins  and  y  extents. 
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To  cancel  the  effect  of  this  command,  so  that  there  is  no  clipping,  pass  None  as  the 
clip_mask  in  XChangeGC  orXSetClipMask. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
Structures 

typedef   struct    { 

short   x,y; 

unsigned  short   width,    height; 
}    XRectangle; 

Errors 

BadAlloc 

BadGC 

BadMatch          Incorrect  ordering  (error  message  server-dependent). 

BadValue 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode,  XSetBackground,  XSetClipMask,  XSetClipOrigin,  XSet- 
Dashes, XSetFillRule, XSetFillStyle, XSetForeground, XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple,  XSetSubwindowMode, XSetTSOrigin. 
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-XHb-C,ien,  Connections /  XSetCIOSeDOWnMOde 

Name 

XSetCloseDownMode  —  change  the  close  down  mode  of  a  client. 

Synopsis 

XSetCloseDownMode  (display,  cl ose_mode ) 
Display  * display; 
int  close_mode; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

close_mode     Specifies  the  client  close  down  mode  you  want.  Pass  one  of  these  constants: 

DestroyAll,  RetainPermanent,  or  RetainTemporary. 

Description 

XSetCloseDownMode  defines  what  will  happen  to  the  client's  resources  at  connection  close. 
A  connection  between  a  client  and  the  server  starts  in  DestroyAll  mode,  and  all  resources 
associated  with  that  connection  will  be  freed  when  the  client  process  dies.  If  the  close  down 
mode  is  RetainTemporary  or  RetainPermanent  when  the  client  dies,  its  resources  live 
on  until  a  call  to  XKillClient.  The  resource  argument  of  XKillClient  can  be  used  to 
specify  which  client  to  kill,  or  it  may  be  the  constant  AllTemporary,  in  which  case  XKill 
Client  kills  all  resources  of  all  clients  that  have  terminated  in  RetainTemporary  mode. 

One  use  of  RetainTemporary  or  RetainPermanent  might  be  to  allow  an  application  to 
recover  from  a  failure  of  the  network  connection  to  the  display  server.  After  restarting,  the 
application  would  need  to  be  able  to  identify  its  own  resources  and  reclaim  control  of  them. 

Errors 

BadValue 

Related  Commands 

XKillClient. 
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Name 

XSetCommand  —  set  the  XA_WM_COMMAND  atom  (command  line  arguments). 

Synopsis 

XSetCommand  (display,  w,  argv,  argc) 
Display  * display ; 
Window  w; 
char  **argv; 
int  argc; 

Arguments 

di  spl ay        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi  spl ay . 

w  Specifies  the  ID  of  the  window  whose  atom  is  to  be  set. 

argv  Specifies  a  pointer  to  the  command  and  arguments  used  to  start  the  application. 

argc  Specifies  the  number  of  arguments. 

Description 

XSetCommand  is  superseded  by  XSetWMCommand  in  Release  4. 

XSetCommand  is  used  by  the  application  to  set  the  XA_WM_COMMAND  property  for  the  window 
manager  with  the  command  and  its  arguments  used  to  invoke  the  application. 

XSetCommand  creates  a  zero-length  property  if  argc  is  zero. 

Use    this    command    only    if    not    calling    XSetStandardProperties    or    XSet- 
WMProperties. 

Errors 

BadAlloc 
BadWindow 

Related  Commands 

XFetchName,  XGetClassHint, XGetlconName, XGetlconSizes,  XGetNormal- 
Hints,  XGetSizeHints, XGetTransientForHint, XGetWMHints,  XGetZoom- 
Hints,XSetClassHint,XSetIconName,XSetIconSizes,XSetNormalHints, 
XSetSizeHints,  XSetTransientForHint, XSetWMHints,  XSetZoomHints, 
XStoreName. 
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—Xlib  -  Graphics  Context- 


XSetDashes 


Name 

XSetDashes  —  set  a  pattern  of  line  dashes  in  a  graphics  context. 

Synopsis 

XSetDashes (display,  gc ,  dash_offset,  dash_list,  n) 
Display  * display ; 
GC  gc; 

int  dash_offset ; 
char  dash_list[]  ; 
int  n; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD i  spl  ay . 

gc  Specifies  the  graphics  context. 

dash_offset  Specifies  the  phase  of  the  pattern  for  the  dashed  line  style. 

das£i_list       Specifies  the  dash  list  for  the  dashed  line  style.  An  odd-length  list  is  equiva 
lent  to  the  same  list  concatenated  with  itself  to  produce  an  even-length  list. 

n  Specifies  the  length  of  the  dash  list  argument. 


First  pixel 
in  line 


Last  pixel 
in  line 


dotted  (3,1) 
dot_dashed  (3,4,3,1) 
short_dashed  (4,4) 
long_dashed  (4,7) 
odd  dashed  (1, 2, 3) 
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Pixels 
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XSetDasheS  (continued)  Xlib  -  Graphics  Context 

Description 

XSetDashes  sets  the  dashes  component  of  a  GC.  The  initial  and  alternating  elements  of 
the  dash_list  argument  are  the  dashes,  the  others  are  the  gaps.  All  of  the  elements  must  be 
nonzero,  with  lengths  measured  in  pixels.  The  dash_offset  argument  defines  the  phase  of 
the  pattern,  specifying  how  many  pixels  into  the  dash_list  the  pattern  should  actually  begin 
in  the  line  drawn  by  the  request. 

n  specifies  the  length  of  dash_list.  An  odd  value  for  n  is  interpreted  as  specifying  the 
dash_list  concatenated  with  itself  to  produce  twice  as  long  a  list. 

Ideally,  a  dash  length  is  measured  along  the  slope  of  the  line,  but  server  implementors  are  only 
required  to  match  this  ideal  for  horizontal  and  vertical  lines.  Failing  the  ideal  semantics,  it  is 
suggested  that  the  length  be  measured  along  the  major  axis  of  the  line.  The  major  axis  is 
defined  as  the  x  axis  for  lines  drawn  at  an  angle  of  between  -45  and  +45  degrees  or  between 
315  and  225  degrees  from  the  x  axis.  For  all  other  lines,  the  major  axis  is  the  y  axis. 

See  Volume  One,  Chapter  5,  The  Graphics  Context,  for  further  information. 

Errors 

BadAlloc 

BadGC 

BadValue          No  values  in  dash_list. 
Element  in  dash_list  is  0. 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode,  XSetBackground, XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetFillRule, XSetFillStyle, XSetForeground, XSet- 
Function,  XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, 
XSetState, XSetStipple, XSetSubwindowMode,  XSetTSOrigin. 
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-x.ib  -  Error  Hand.ing /  XSetErrorHandler 

Name 

XSetErrorHandler  —  set  a  nonfatal  error  event  handler. 

Synopsis 

In  Release  3: 

XSetErrorHandler (handler) 

int  (*  handler)  (Display  *,  XErrorEvent  *) 
InRelease4:  int  (*XSetErrorHandler  (handler)  )() 

int  (*  handler)  (Display  *,  XErrorEvent  *) 

Arguments 

handler  The  user-defined  function  to  be  called  to  handle  error  events.   If  a  NULL 

pointer,  reinvoke  the  default  handler,  which  prints  a  message  and  exits. 

Description 

The  error  handler  function  specified  in  handler  will  be  called  by  Xlib  whenever  an  XError 
event  is  received.  These  are  nonfatal  conditions,  such  as  unexpected  values  for  arguments,  or  a 
failure  in  server  memory  allocation.  It  is  acceptable  for  this  procedure  to  return,  though  the 
default  handler  simply  prints  a  message  and  exits.  However,  the  error  handler  should  NOT  per 
form  any  operations  (directly  or  indirectly)  on  the  server. 

In  Release  4,  XSetErrorHandler  returns  a  pointer  to  the  previous  error  handler. 

The  function  is  called  with  two  arguments,  the  display  variable  and  a  pointer  to  the  XError 
Event  structure.  Here  is  a  trivial  example  of  a  user-defined  error  handler: 

int  myhandler  (display,  myerr) 
Display  *display; 
XErrorEvent  *myerr; 
{ 

char  msg[80] ; 

XGetErrorText  (display,  myerr->error_code,  msg,  80); 

fprintf (stderr,  "Error  code  %s\n",  msg); 
} 

This  is  how  the  example  routine  would  be  used  in  XSetErrorHandler. 
XSetErrorHandler (myhandler) / 

Note  that  XSetErrorHandler  is  one  of  the  few  routines  that  does  not  require  a  display 
argument.  The  routine  that  calls  the  error  handler  gets  the  display  variable  from  the  XError 
Event  structure. 

The  error  handler  is  not  called  on  BadName  errors  from  OpenFont,  LookupColor,  and 
AllocNamedColor  protocol  requests,  on  BadFont  errors  from  a  QueryFont  protocol 
request,  or  on  BadAlloc  or  BadAccess  errors.  These  errors  are  all  indicated  by  Status 
return  value  of  zero  in  the  corresponding  Xlib  routines,  which  must  be  caught  and  handled  by 
the  application. 

Use  XlOErrorHandler  to  provide  a  handler  for  I/O  errors  such  as  network  failures  or  server 
host  crashes. 
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In  the  XErrorEvent  structure  shown  below,  the  serial  member  is  the  number  of  requests 
(starting  from  1)  sent  over  the  network  connection  since  it  was  opened.  It  is  the  number  that 
was  the  value  of  the  request  sequence  number  immediately  after  the  failing  call  was  made.  The 
request_code  member  is  a  protocol  representation  of  the  name  of  the  procedure  that  failed 
and  is  defined  in  <Xll/X.h>. 

For  more  information,  see  Volume  One,  Chapter  3,  Basic  Window  Program. 
Structures 

typedef   struct    { 
int   type 

Display   *display;  /*   display  the   event   was   read   from   */ 

XID   resourceid;  /*    resource    ID    */ 

unsigned   long  serial;       /*    serial   number  of   failed  request    */ 
unsigned   char   error_code; /*    error   code   of    failed   request    */ 
unsigned   char   request_code; /*   major   opcode   of    failed   request    */ 
unsigned   char   minor_code; /*   minor   opcode   of    failed   request    */ 

}    XErrorEvent; 

Related  Commands 

XDisplayName, XGetErrorDatabaseText, XGetErrorText,  XSetAf ter- 
Function,  XSetlOErrorHandler, XSynchronize. 
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—Xlib  -  Graphics  Context- 


XSetFillRule 


Name 

XSetFillRule  —  set  the  fill  rule  in  a  graphics  context. 

Synopsis 

XSetFillRule  (display,  gc,  fill_rule) 
Display  * display; 
GC  gc; 
int  fill_rule; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDi splay. 

gc  Specifies  the  graphics  context. 

fill_rule       Specifies  the  fill  rule  you  want  to  set  for  the  specified  graphics  context.  Pos 
sible  values  are  EvenOddRule  orWindingRule. 

Description 

XSetFillRule  sets  the  fill_rule  component  of  a  GC.  The  fill_rule  member  of  the 
GC  determines  what  pixels  are  drawn  in  XFillPolygon  requests.  Simply  put,  Winding- 
Rule  fills  overlapping  areas  of  the  polygon,  while  EvenOddRule  does  not  fill  areas  that 
overlap  an  odd  number  of  times.  Technically,  EvenOddRule  means  that  the  point  is  drawn  if 
an  arbitrary  ray  drawn  from  the  point  would  cross  the  path  determined  by  the  request  an  odd 
number  of  times.  WindingRule  indicates  that  a  point  is  drawn  if  a  point  crosses  an  unequal 
number  of  clockwise  and  counterclockwise  path  segments,  as  seen  from  the  point. 


Outline  of  polygon  to  fill 


EvenOddRul< 


WindingRule 
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XSetFillRule  (continued)  Xlib  -  Graphics  Context 

A  clockwise-directed  path  segment  is  one  which  crosses  the  ray  from  left  to  right  as  observed 
from  the  point.  A  counterclockwise  segment  is  one  which  crosses  the  ray  from  right  to  left  as 
observed  from  the  point.  The  case  where  a  directed  line  segment  is  coincident  with  the  ray  is 
uninteresting  because  you  can  simply  choose  a  different  ray  that  is  not  coincident  with  a  seg 
ment 

All  calculations  are  performed  on  infinitely  small  points,  so  that  if  any  point  within  a  pixel  is 
considered  inside,  the  entire  pixel  is  drawn.  Pixels  with  centers  exactly  on  boundaries  are  con 
sidered  inside  only  if  the  filled  area  is  to  the  right,  except  that  on  horizontal  boundaries,  the 
pixel  is  considered  inside  only  if  the  filled  area  is  below  the  pixel. 

See  Volume  One,  Chapter  5,  The  Graphics  Context,  for  more  information. 

Errors 

BadGC 
BadValue 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode,  XSetBackground, XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillStyle,  XSetForeground,  XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple,  XSetSubwindowMode, XSetTSOrigin. 
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—Xlib  -  Graphics  Context- 


XSetFillStyle 


Name 

XSetFillStyle  —  set  the  fill  style  in  a  graphics  context. 

Synopsis 

XSetFillStyle  (display,    gc ,    fill_style) 
Display   *  display; 
GC    gc; 
int    fill_style; 


Arguments 

display 


Specifies  a  connection  to  an  X  server;  returned  from  xopenDi splay. 


gc  Specifies  the  graphics  context. 

fill_style     Specifies  the  fill  style  for  the  specified  graphics  context.  Possible  values  are 

FillSolid,      Fill-Tiled,      FillStippled,      or      FillOpaque- 
Stippled. 


GC  foreground 
GC  background 
Undrawn  Pixels  M 


Tile 


Stipple 


FillSolid 


FillTiled 


FillStippled    FillOpaqueStippled 


Description 

XSetFillStyle  sets  the  fill_style  component  of  a  GC.  The  fill_style  defines  the 
contents  of  the  source  for  line,  text,  and  fill  requests.  FillSolid  indicates  that  the  pixels  rep 
resented  by  set  bits  in  the  source  are  drawn  in  the  foreground  pixel  value,  and  unset  bits  in 
the  source  are  not  drawn.  FillTiled  uses  the  tile  specified  in  the  GC  to  determine  the 
pixel  values  for  set  bits  in  the  source.  FillOpaqueStippled  specifies  that  bits  set  in  the 
stipple  are  drawn  in  the  foreground  pixel  value  and  unset  bits  are  drawn  in  the  back 
ground.  FillStippled  draws  bits  set  in  the  source  and  set  in  the  stipple  in  the  fore 
ground  color,  and  leaves  unset  bits  alone. 
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XSetFillStyle  (continued)  Xlib  -  Graphics  Context 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
Errors 

BadGC 
BadValue 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode,  XSetBackground, XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule,  XSetForeground,  XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple, XSetSubwindowMode, XSetTSOrigin. 
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Name 

XSetFont  —  set  the  current  font  in  a  graphics  context. 

Synopsis 

XSetFont  (display,  gc,  font) 
Display  *  display; 
GC  gc; 
Font  font; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi  spl  ay. 

gc  Specifies  the  graphics  context. 

f  on  t  Specifies  the  ID  of  the  font  to  be  used. 

Description 

XSetFont  sets  the  font  in  the  GC.  Text  drawing  requests  using  this  GC  will  use  this  font 
only  if  the  font  is  loaded.  Otherwise,  the  text  will  not  be  drawn. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
Errors 

BadFont 
BadGC 

Related  Commands 

XCreateFontCursor,  XFreeFont,  XFreeFontlnf  o,  XFreeFontNames,  XFree- 
FontPath,  XGetFontPath,  XGetFontProperty,  XListFonts,  XListFontsWith- 
Inf  o,  XLoadFont,  XLoadQueryFont,  XQueryFont,  XSetFontPath,  XUnloadFont. 
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XSetFontPath  ~\ 


•Xlib- Fonts- 


Name 

XSetFontPath  —  set  the  font  search  path. 

Synopsis 

XSetFontPath ( display,  directories,  ndirs) 
Display  *  display; 
char  ** directories; 
int  ndirs; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

directories  Specifies  the  directory  path  used  to  look  for  the  font.  Setting  the  path  to  the 
empty  list  restores  the  default  path  defined  for  the  X  server. 

ndi  rs  Specifies  the  number  of  directories  in  the  path. 

Description 

XSetFontPath  defines  the  directory  search  path  for  font  lookup  for  all  clients.  Therefore  the 
user  should  construct  a  new  directory  search  path  carefully  by  adding  to  the  old  directory 
search  path  obtained  by  XGetFontPath.  Passing  an  invalid  path  can  result  in  preventing  the 
server  from  accessing  any  fonts.  Also  avoid  restoring  the  default  path,  since  some  other  client 
may  have  changed  the  path  on  purpose. 

The  interpretation  of  the  strings  is  operating  system  dependent,  but  they  are  intended  to  specify 
directories  to  be  searched  in  the  order  listed.  Also,  the  contents  of  these  strings  are  operating 
system  specific  and  are  not  intended  to  be  used  by  client  applications. 

The  meaning  of  errors  from  this  request  is  system  specific. 

Errors 

BadValue 

Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o, XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith- 
Inf o, XLoadFont, XLoadQueryFont, XQueryFont, XSetFont,  XUnloadFont. 
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-x,lb-Graph,c,con,«, /  XSetForeground 

Name 

XSetForeground  —  set  the  foreground  pixel  value  in  a  graphics  context. 

Synopsis 

XSetForeground (display,  gc,  foreground) 
Display  * display ; 
GC  gc; 
unsigned  long  foreground; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

gc  Specifies  the  graphics  context. 

foreground     Specifies  the  foreground  pixel  value  you  want  for  the  specified  graphics  con 
text 

Description 

XSetForeground  sets  the  foreground  component  in  a  GC.  This  pixel  value  is  used  for 
set  bits  in  the  source  according  to  the  f  ill_style.  This  pixel  value  must  be  returned  by 
BlackPixel,  whitePixel,  or  a  routine  that  allocates  colors. 

See  Volume  One,  Chapter  5,  The  Graphics  Context,  for  more  information  on  the  GC. 

Errors 

BadGC 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask,  XSetClipOrigin,  XSetClip- 
Rectangles, XSetDashes, XSetFillRule,  XSetFillStyle,  XSetFunction, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple,  XSetSubwindowMode,  XSetTSOrigin. 
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XSetFu  notion 


X 


Xlib  -  Graphics  Context — 


Name 

XSetFunction  —  set  the  bitwise  logical  operation  in  a  graphics  context. 

Synopsis 

XSetFunction (display,  gc,  function) 
Display  *display; 
GC  gc; 
int  function; 


Arguments 

display 

gc 

function 


Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 
Specifies  the  graphics  context. 

Specifies  the  logical  operation  you  want  for  the  specified  graphics  context.  See 
Description  for  the  choices  and  their  meanings. 

Description 

XSetFunction  sets  the  logical  operation  applied  between  the  source  pixel  values  (generated 
by  the  drawing  request)  and  existing  destination  pixel  values  (already  in  the  window  or  pix- 
map)  to  generate  the  final  destination  pixel  values  in  a  drawing  request  (what  is  actually  drawn 
to  the  window  or  pixmap).  Of  course,  the  plane_mask  and  clip_mask  in  the  GC  also 
affect  this  operation  by  preventing  drawing  to  planes  and  pixels  respectively.  GXcopy,  GXin- 
vert,  and  GXxor  are  the  only  logical  operations  that  are  commonly  used. 

See  Volume  One,  Chapter  5,  The  Graphics  Context,  for  more  information  about  the  logical 
function. 


The  function  syn 
Symbol 

ibolsar 
Bit 

d  their  logical  definitions  are: 
Meaning 

GXclear 

0x0 

0 

GXand 

Oxl 

src  AND  dst 

GXandReverse 

0x2 

srcAND(NOTdst) 

GXcopy 

0x3 

src 

GXandlnverted 

0x4 

(NOT  src)  AND  dst 

GXnoop 

0x5 

dst 

GXxor 

0x6 

src  XOR  dst 

GXor 

0x7 

src  OR  dst 

GXnor 

0x8 

(NOT  src)  AND  (NOT  dst) 

GXequiv 

0x9 

(NOT  src)  XOR  dst 

GXinvert 

Oxa 

(NOT  dst) 

GXorReverse 

Oxb 

src  OR  (NOT  dst) 

GXcopy  Inverted 

Oxc 

(NOT  src) 

GXorlnverted 

Oxd 

(NOT  src)  OR  dst 

GXnand 

Oxe 

(NOT  src)  OR  (NOT  dst) 

GXset 

Oxf 

1 
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Errors 

BadGC 
BadValue 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode,  XSetBackground,  XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule,  XSetFillStyle,  XSetForeground, 
XSetGraphicsExposures, XSetLineAttributes, XSetPlaneMask, XSetState, 
XSetStipple, XSetSubwindowMode,  XSetTSOrigin. 


Xlib  Reference  Manual  445 


XSetGraphicsExposures  \ 


•Xlib  -  Graphics  Context- 


Name 

XSetGraphicsExposures  —  set  the  graphics_exposures  component  in  a  graphics  context. 

Synopsis 

XSetGraphicsExposures (  display,  gc ,  graph! cs_exposures) 
Display  *display; 
GC  gc; 
Bool  graphics_exposures ; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

gc  Specifies  the  graphics  context. 

graphi cs_exposures 

Specifies  whether  you  want  GraphicsExpose  and  NoExpose  events  when 
calling  XCopyArea  and  XCopyPlane  with  this  graphics  context. 

Description 

XSetGraphicsExposure  sets  the  graphics_exposures  member  of  a  GC.  If 
graphi cs_exposures  is  True,  GraphicsExpose  events  will  be  generated  when 
XCopyArea  and  XCopyPlane  requests  cannot  be  completely  satisfied  because  a  source 
region  is  obscured,  and  NoExpose  events  are  generated  when  they  can  be  completely  satis 
fied.  If  graphi cs_exposures  is  False,  these  events  are  not  generated. 

These  events  are  not  selected  in  the  normal  way  with  XSelect Input.  Setting  the 
graphi cs_exposures  member  of  the  GC  used  in  the  CopyArea  or  CopyPlane  request 
is  the  only  way  to  select  these  events. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
Errors 

BadGC 
BadValue 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule,  XSetFillStyle, XSetForeground, 
XSetFunction, XSetLineAttributes, XSetPlaneMask, XSetState, XSet- 
Stipple,  XSetSubwindowMode, XSetTSOrigin. 
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-X,,b-W,ndowManagerH,n,s '  XSetlCOnNaiTie 

Name 

XSetlconName  —  set  the  name  to  be  displayed  in  a  window's  icon. 

Synopsis 

XSetlconName  (display,  w,  icon_name) 
Display  * display ; 
Window  w; 
char  *icon_name; 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  ID  of  the  window  whose  icon  name  is  being  set. 

i  con_name  Specifies  the  name  to  be  displayed  in  the  window's  icon.  The  name  should  be 
a  null-terminated  string.  This  name  is  returned  by  any  subsequent  call  to 
XGetlconName. 

Description 

XSetlconName  is  superseded  by  XSetWMlconName  in  Release  4. 

XSetlconName  sets  the  XA_WM_ICON_NAME  property  for  a  window.  This  is  usually  set  by  an 
application  for  the  window  manager.  The  name  should  be  short,  since  it  is  to  be  displayed  in 
association  with  an  icon. 

XSetStandardProperties  (in  Release  4)  or  XSetWMProperties  (in  Release  4)  also 
set  this  property. 

For  more  information,  see  Volume  One,  Chapter  IQJnterclient  Communication. 
Errors 

BadAlloc 
BadWindow 

Related  Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetCorranand,  XSetlconSizes, XSetNormalHints, 
XSetSizeHints,  XSetTransientForHint, XSetWMHints,  XSetZoomHints, 
XStoreName. 
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XSetlconSizes  V XIib  _  Window  Manager  Hints_ 

Name 

XSetlconSizes  —  set  the  value  of  the  XA_WM_ICON_SIZE  property. 

Synopsis 

XSetlconSizes (display,  w,  size_list,  count) 
Display  * display ; 
Window  ur; 

XlconSize  *size_list; 
int  count; 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi spl ay . 

w  Specifies  the  ID  of  the  window  whose  icon  size  property  is  to  be  set.  Nor 

mally  the  root  window. 

si  ze_l  i  s  t       Specifies  a  pointer  to  the  size  list. 

count  Specifies  the  number  of  items  in  the  size  list. 

Description 

XSetlconSizes  is  normally  used  by  a  window  manager  to  set  the  range  of  preferred  icon 
sizes  in  the  XA_WM_ICON_SIZE  property  of  the  root  window. 

Applications  can  then  read  the  property  with  XGetlconSizes. 
Structures 

typedef  struct  { 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 
}  XlconSize; 

Errors 

BadAlloc 
BadWindow 

Related  Commands 

XAllocIconSize, XFetchName, XGetClassHint, XGetlconName, XGetlcon 
Sizes,  XGetNormalHints,XGetSizeHints,XGetTransientForHint,XGet- 
WMHints, XGetZoomHints, XSetClassHint, XSetCommand,  XSetlconName, 
XSetNormalHints, XSetSizeHints,  XSetTransientForHint, XSetWMHints, 
XSetZoomHints,  XStoreName. 
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J  XSetlnputFocus 

— Xlib  -  Input  Handling ' 

Name 

XSetlnputFocus  —  set  the  keyboard  focus  window. 

Synopsis 

XSetlnputFocus (display,  focus,  revert_to,  time) 
Display  *display; 
Window  focus; 
int  revert_to; 
Time  time; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

focus  Specifies  the  ID  of  the  window  you  want  to  be  the  keyboard  focus.  Pass  the 

window  ID,  PointerRoot,  or  None. 

revert_to  Specifies  which  window  the  keyboard  focus  reverts  to  if  the  focus  window 
becomes  not  viewable.  Pass  one  of  these  constants:  RevertToParent, 
RevertToPointerRoot,  or  RevertToNone.  Must  not  be  a  window  ID. 

time  Specifies  the  time  when  the  focus  change  should  take  place.   Pass  either  a 

timestamp,  expressed  in  milliseconds,  or  the  constant  CurrentTime.  Also 
returns  the  time  of  the  focus  change  when  CurrentTime  is  specified. 

Description 

XSetlnputFocus  changes  the  keyboard  focus  and  the  last-focus-change  time.  The  function 
has  no  effect  if  time  is  earlier  than  the  current  last-focus-change  time  or  later  than  the  current 
X  server  time.  Otherwise,  the  last-focus-change  time  is  set  to  the  specified  time,  with 
CurrentTime  replaced  by  the  current  X  server  time. 

XSetlnputFocus  generates  Focusln  and  FocusOut  events  if  focus  is  different  from 
the  current  focus. 

XSetlnputFocus  executes  as  follows,  depending  on  what  value  you  assign  to  the  focus 
argument: 

If  you  assign  None,  all  keyboard  events  are  discarded  until  you  set  a  new  focus  window. 
In  this  case,  revert_to  is  ignored. 

If  you  assign  a  window  ID,  it  becomes  the  main  keyboard's  focus  window.  If  a  generated 
keyboard  event  would  normally  be  reported  to  this  window  or  one  of  its  inferiors,  the 
event  is  reported  normally;  otherwise,  the  event  is  reported  to  the  focus  window.  The 
specified  focus  window  must  be  viewable  at  the  time  of  the  request  (else  a  BadMatch 
error).  If  the  focus  window  later  becomes  not  viewable,  the  focus  window  will  change  to 
the  re vert_ to  argument 

•  If  you  assign  PointerRoot,  the  focus  window  is  dynamically  taken  to  be  the  root  win 
dow  of  whatever  screen  the  pointer  is  on  at  each  keyboard  event  In  this  case, 
revert_to  is  ignored.  This  is  the  default  keyboard  focus  setting. 

If  the  focus  window  later  becomes  not  viewable,  XSetlnputFocus  evaluates  the 
re vert_ to  argument  to  determine  the  new  focus  window: 
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If  you  assign  RevertToParent,  the  focus  reverts  to  the  parent  (or  the  closest  viewable 
ancestor)  automatically  with  a  new  revert_to  argument  of  Revert ToName. 

•  If  you  assign  RevertToPointerRoot  or  RevertToNone,  the  focus  reverts  to  that 
value  automatically.  Focus  in  and  FocusOut  events  are  generated  when  the  focus 
reverts,  but  the  last  focus  change  time  is  not  affected. 

Errors 

BadMatch          focus  window  not  viewable  when  XSetlnputFocus  called. 

BadValue 
BadWindow 

Related  Commands 

QLength, XAllowEvents, XChecklf Event, XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent,  XEventsQueued, 
XGetlnputFocus.XGetMotionEvents, XI f Event,  XMaskEvent,XNextEvent, 
XPeekEvent, XPeeklf Event, XPending,  XPutBackEvent, XSelectlnput, 
XSendEvent , XSynchroni  ze, XWindowEvent. 
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f  XSetlOErrorHandler 

— Xlib  -  Error  Handling ' 

Name 

XSetErrorHandler  —  set  a  nonfatal  error  event  handler. 

Synopsis 

In  Release  3: 

XSetlOErrorHandler  (ha/idler) 

int    (*  handler)  (Display   *,    XErrorEvent    *) 
I n  Release  4: 
int    (*XSetIOErrorHandler (handler) )  () 

int    (*  handler)  (Display   *,    XErrorEvent    *) 

Arguments 

handler  Specifies  user-defined  fatal  error  handling  routine.    If  NULL,  reinvoke  the 

default  fatal  error  handler. 

Description 

XSetlOErrorHandler  specifies  a  user-defined  error  handling  routine  for  fatal  errors.  This 
error  handler  will  be  called  by  Xlib  if  any  sort  of  system  call  error  occurs,  such  as  the  connec 
tion  to  the  server  being  lost.  The  called  routine  should  not  return.  If  the  I/O  error  handler  does 
return,  the  client  process  will  exit. 

If  handler  is  a  NULL  pointer,  the  default  error  handler  is  reinstated.  The  default  I/O  error 
handler  prints  an  error  message  and  exits. 

In  Release  4,  XSetlOErrorHandler  returns  a  pointer  to  the  previous  error  handler. 
For  more  information,  see  Volume  One,  Chapter  3,  Basic  Window  Program. 

Related  Commands 

XDisplayName,  XGetErrorDatabaseText, XGetErrorText, XSetAf ter- 
Function, XSetErrorHandler,  XSynchronize. 
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XSetLineAttributes 


X 


•Xlib  -  Graphics  Context- 


Name 

XSetLineAttributes  —  set  the  line  drawing  components  in  a  graphics  context. 

Synopsis 

XSetLineAttributes (display,    gc,    line_width,    line_style, 

cap_style ,    join_style) 
Display   *display; 
GC   gc; 

unsigned  int   li/ie_v/idth; 
int   li/ie_style; 
int    cap_style; 
int    join_style; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

gc  Specifies  the  graphics  context. 


line_style 


LineSolid 


LineOnOffDash 


Line/Double  Dash 


cap_style 

CapNotLast          CapButt 


join_style 


CapRound 


CapPro jecting 


JoinRound 


JoinMiter 


N\ 


JoinBevel 


fill_style 

Ti|e  GC  foreground  |         GC  background  Q        Undrawn  Pixels  [x] 

FillSolid        FillTiled      FillStippled  FillOpaqueStippled 

Stipple 
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line_width     Specifies  the  line  width  in  the  specified  graphics  context. 

line_style     Specifies  the  line  style  in  the  specified  graphics  context.  Possible  values  are 

LineSolid,  LineOnOf  f  Dash,  or  LineDoubleDash. 

cap_style  Specifies  the  line  and  cap  style  in  the  specified  graphics  context.  Possible 
values  are  CapNotLast,  CapButt,  CapRound,  or  CapPro  jecting. 

join_style  Specifies  the  line-join  style  in  the  specified  graphics  context.  Possible  values 
are  JoinMiter,  JoinRound,  or  JoinBevel.  If  you  specify  Join- 
Mitre,  JoinBevel  is  used  instead  if  the  angle  separating  the  two  lines  is 
less  than  1 1  degrees. 

Description 

XSetLineAttributes  sets  four  types  of  line  characteristics  in  the  GC:    line_width, 
line_style,  cap_style,  and  join_style. 

See  the  description  of  line  and  join  styles  in  Volume  One,  Chapter  5,  The  Graphics  Context. 
See  also  XSetDashes. 

A  line_width  of  zero  (0)  means  to  use  the  fastest  algorithm  for  drawing  a  line  of  one  pixel 
width.  These  lines  may  not  meet  properly  with  lines  specified  as  width  one  or  more. 

Errors 

BadGC 
BadValue 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask, XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule, XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetPlaneMask, XSetState,  XSet- 
Stipple, XSetSubwindowMode, XSetTSOrigin. 
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XSetModifierMapping  \ x,,b- Keyboard- 

Name 

XSetModifierMapping  —  set  keycodes  to  be  used  as  modifiers  (Shift,  Control,  etc.). 

Synopsis 

int  XSetModif ierMapping ( display,  mod_map) 
Display  *display; 
XModif ierKeymap  *mod_map; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

mod_map        Specifies  the  XModif  ierKeymap  structure  containing  the  desired  modifier 
key  codes. 

Description 

XSetModifierMapping  is  one  of  two  ways  to  specify  the  keycodes  of  the  keys  that  are  to 
be  used  as  modifiers  (like  Shift,  Control,  etc.).  XSetModifierMapping  specifies  all  the 
keycodes  for  all  the  modifiers  at  once.  The  other,  easier,  way  is  to  use  xinsert- 
Modif  iermapEntry  and  XDeleteModif  iermapEntry,  which  add  or  delete  a  single 
keycode  for  a  single  modifier  key.  XSetModifierMapping  does  the  work  in  a  single  call, 
but  the  price  of  this  call  is  that  you  need  to  manually  set  up  the  XModif  ierKeymap  structure 
pointed  to  by  mod_map.  This  requires  you  to  know  how  the  XModif  ierKeymap  structure  is 
defined  and  organized,  as  described  in  the  next  three  paragraphs. 

The  XModif  ierKeymap  structure  for  the  mod_map  argument  should  be  created  using 
XNewModif  ierMap  or  XGetModif  ierMapping.  The  Max_keypermod  element  of  the 
structure  specifies  the  maximum  number  of  keycodes  that  can  be  mapped  to  each  modifier.  You 
define  this  number  but  there  may  be  an  upper  limit  on  a  particular  server. 

The  modif  iermap  element  of  the  structure  is  an  array  of  keycodes.  There  are  eight  by 
max_keypermod  keycodes  in  this  array:  eight  because  there  are  eight  modifiers,  and 
max_keypermod  because  that  is  the  number  of  keycodes  that  must  be  reserved  for  each  mod 
ifier. 

The  eight  modifiers  are  represented  by  the  constants  ShiftMaplndex,  LockMaplndex, 
ControlMapIndex,  ModlMapIndex,  Mod2MapIndex,  ModSMapIndex,  Mod4Map- 
Index,  and  ModSMapIndex.  These  are  not  actually  used  as  arguments,  but  they  are  conve 
nient  for  referring  to  each  row  in  the  modif  iermap  structure  while  filling  it.  The  definitions 
of  these  constants  are  shown  in  the  Structures  section  below. 

Now  you  can  interpret  the  modif  iermap  array.  For  each  modifier  in  a  given  modifier- 
map,  the  keycodes  which  correspond  are  from  modif  iermap  [index  * 
max_keypermod]  to  modif iermap [( (index  +  1)  *  max_keyspermod)  -1] 
where  index  is  the  appropriate  modifier  index  definition  (ShiftMaplndex,  LockMap 
lndex,  etc.).  You  must  set  the  mod_map  array  up  properly  before  calling  XSetModifier 
Mapping.  Now  you  know  why  XInsertModif  ierMapEntry  and  XDeleteModif ier- 
MapEntry  were  created! 

Zero  keycodes  are  ignored.  No  keycode  may  appear  twice  anywhere  in  the  map  (otherwise,  a 
BadValue  error  is  generated).  In  addition,  all  of  the  nonzero  keycodes  must  be  in  the  range 


454  Xlib  Reference  Manual 


Xlib  -  Keyboard  (continued)  XSetModifierMapping 

specified  by  min_keycode  and  max_keycode  in  the  Display  structure  (otherwise  a 
BadValue  error  occurs). 

A  server  can  impose  restrictions  on  how  modifiers  can  be  changed.  For  example,  certain  keys 
may  not  generate  up  transitions  in  hardware,  certain  keys  may  always  auto-repeat  and  therefore 
be  unsuitable  for  use  as  modifiers,  or  multiple  modifier  keys  may  not  be  supported.  If  a  restric 
tion  is  violated,  then  the  status  reply  is  MappingFailed,  and  none  of  the  modifiers  are 
changed. 

XSetModifierMapping  returns  MappingSuccess  or  MappingBusy.  The  server  gen 
erates  a  MappingNotif  y  event  on  a  MappingSuccess  status.  If  the  new  keycodes  speci 
fied  for  a  modifier  differ  from  those  currently  defined  and  any  (current  or  new)  keys  for  that 
modifier  are  in  the  down  state,  then  the  status  reply  is  MappingBusy,  and  none  of  the  modifi 
ers  are  changed. 

A  value  of  zero  for  modif  iermap  indicates  that  no  keys  are  valid  as  any  modifier. 
Structures 

typedef  struct  { 

int  max_keypermod;      /*  server's  max  #  of  keys  per  modifier  */ 
KeyCode  *modif iermap;   /*  an  8  by  max_keypermod  array  */ 

}  XModifierKeymap; 


c  c 


/*  Modifier  name  symbols.  Used  to  build  a  SetModif ierMapping  request 

to  read  a  GetModif ierMapping  request.  */ 

#define  ShiftMapIndex  0 

#define  LockMapIndex  1 

#define  ControlMapIndex  2 

#define  ModlMapIndex  3 

#define  Mod2MapIndex  4 

tdefine  Mod3MapIndex  5 

#define  ModlMapIndex  6 

#define  ModSMapIndex  7 

Errors 

BadAlloc 

BadValue         Keycode  appears  twice  in  the  map. 

Keycode  <  disp-Zay->min_keycode  or 
keycode  >  display->max_keycode. 

Related  Commands 

XChangeKeyboardMapping, XDeleteModif iermapEntry, XDelete- 
Modif iermapEntry, XFreeModif iermap, XGetKeyboardMapping, XGet- 
Modif ierMapping,  XInsertModif iermapEntry,  XInsertModif iermapEntry, 
XKeycodeToKeysym,  XKeysymToKeycode, XKeysymToString, XLookupKeysym, 
XLookupString,  XNewModif  ierMap,  XQueryKeymap,  XRebindKeysym, 
XRefreshKeyboardMapping,  XStringToKeysym. 
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Name 

XSetNormalHints  —  set  the  size  hints  property  of  a  window  in  normal  state  (not  zoomed  or 
iconified). 

Synopsis 

void  XSetNormalHints (display,  w,  hints) 
Display  *display; 
Window  w, 
XSizeHints  *hints; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID. 

hints  Specifies  a  pointer  to  the  sizing  hints  for  the  window  in  its  normal  state. 

Description 

XSetNormalHints  has  been  superseded  by  XSetWMNormalHints  as  of  Release  4. 

XSetNormalHints  sets  the  XA_WM_NORMAL_HINTS  property  for  the  specified  window. 
Applications  use  XSetNormalHints  to  inform  the  window  manager  of  the  size  or  position 
desirable  for  that  window.  In  addition,  an  application  wanting  to  move  or  resize  itself  should 
call  XSetNormalHints  specifying  its  new  desired  location  and  size,  in  addition  to  making 
direct  X  calls  to  move  or  resize.  This  is  because  some  window  managers  may  redirect  window 
configuration  requests,  but  ignore  the  resulting  events  and  pay  attention  to  property  changes 
instead. 

To  set  size  hints,  an  application  must  assign  values  to  the  appropriate  elements  in  the  hints 
structure,  and  also  set  the  flags  field  of  the  structure  to  indicate  which  members  have 
assigned  values  and  the  source  of  the  assignment  These  flags  are  listed  in  the  Structures  sec 
tion  below. 

For  more  information  on  using  hints,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Structures 

typedef  struct  { 

long  flags;     /*  which  fields  in  structure  are  defined  */ 

int  x,  y; 

int  width,  height; 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x;     /*  numerator  */ 

int  y;     /*  denominator  */ 
}  min_aspect,  max_aspect; 
}  XSizeHints;      /*~new  fields  in  R4  here  */ 
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#define  USPosition  (1L  «  0)  /*  user  specified  x,  y  */ 

#define  USSize      (1L  «  1)  /*  user  specified  width,  height  */ 

tdefine  PPosition  (1L  «  2)  /*  program  specified  position  */ 

#define  PSize  (1L  «  3)  /*  program  specified  size  */ 

tdefine  PMinSize  (1L  «  4)  /*  program  specified  minimum  size  */ 

tdefine  PMaxSize  (1L  «  5)  /*  program  specified  maximum  size  */ 

tdefine  PResizelnc  (1L  «  6)  /*  program  specified  resize  increments  */ 

tdefine  PAspect  (1L  «  7)  /*  program  specified  min/max  aspect  ratios  */ 

tdefine  PAllHints  (PPosition I PSize | PMinSize I PMaxSize I PResizelnc | PAspect) 

Errors 

BadAlloc 
BadWindow 

Related  Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints,XGetSizeHints,XGetTransientForHint,XGetWMHints,XGetZoom- 
Hints,XSetClassHint,XSetCommand,XSetIconName,XSetIconSizes,XSet- 
SizeHints, XSetTransientForHint, XSetWMHints, XSetZoomHints, XStore- 
Name. 
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XSetPlaneMask  \ Xlib  _  Graphlcs  Comext_ 

Name 

XSetPlaneMask  —  set  the  plane  mask  in  a  graphics  context. 

Synopsis 

XSetPlaneMask (display,  gc,  plane_mask) 
Display  * display ; 
GC  gc; 
unsigned  long  plane_mask; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

gc  Specifies  the  graphics  context. 

plane_mask     Specifies  the  plane  mask.  You  can  use  the  macro  AllPlanes  if  desired. 

Description 

XSetPlaneMask  sets  the  plane_mask  component  of  the  specified  GC.  The  plane_mask 
determines  which  planes  of  the  destination  drawable  are  affected  by  a  graphics  request. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 

Errors 

BadGC 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule,  XSetFillStyle,  XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetState, 
XSetStipple,  XSetSubwindowMode, XSetTSOrigin. 
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j  XSetPointerMapping 


Name 

XSetPointerMapping  —  set  the  pointer  button  mapping. 

Synopsis 

int  XSetPointerMapping  (display,  map,  nmap) 
Display  * display; 
unsigned  char  map[] ; 
int  nmap; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

map  Specifies  the  mapping  list. 

nmap  Specifies  the  number  of  items  in  the  mapping  list. 

Description 

XSetPointerMapping  sets  the  mapping  of  the  pointer  buttons.  Elements  of  the  map  list 
are  indexed  starting  from  1.  The  length  of  the  list  nmap  must  be  the  same  as  XGet Pointer- 
Mapping  returns  (you  must  call  that  first).  The  index  is  a  physical  button  number,  and  the  ele 
ment  of  the  list  defines  the  effective  button  number.  In  other  words,  if  map  [2]  is  set  to  1, 
when  the  second  physical  button  is  pressed,  a  ButtonPress  event  will  be  generated  if  But- 
tonlMask  was  selected  but  not  if  Button2Mask  was  selected.  The  button  member  in  the 
event  will  read  Buttonl. 

No  two  elements  can  have  the  same  nonzero  value  (else  a  BadValue  error).  A  value  of  zero 
for  an  element  of  map  disables  a  button,  and  values  for  elements  are  not  restricted  in  value  by 
the  number  of  physical  buttons.  If  any  of  the  buttons  to  be  altered  are  currently  in  the  down 
state,  the  returned  value  is  MappingBusy  and  the  mapping  is  not  changed. 

This  function  returns  either  MappingSuccess  or  MappingBusy.  XSetPointer 
Mapping  generates  a  MappingNotif  y  event  when  it  returns  MappingSuccess. 

Errors 

BadValue          Two  elements  of  map  [  ]  have  same  nonzero  value. 

nmap  not  equal  to  XGetPointerMapping  return  value. 

Related  Commands 

XChangeActivePointerGrab, XChangePointerControl, XGetPointer- 
Control,  XGetPointerMapping, XGrabPointer, XQueryPointer, XUngrab- 
Pointer,  XWarpPointer. 
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Name 

XSetRGBColormaps  —  set  an  XStandardColormap  structure. 
Synopsis 

void  XSetRGBColormaps ( display,    w,    std_colormap,    count,    prop 
erty) 

Display    *display; 
Window    w; 

XStandardColormap    * std_col or/nap; 
int    count; 
Atom  property; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  window. 

std_col  or/nap 

Specifies  the  XStandardColormap  structure  to  be  used. 

count  Specifies  the  number  of  colormaps . 

property         Specifies  the  property  name. 

Availability 

Release  4  and  later. 

Description 

XSetRGBColormaps  replaces  the  RGB  colormap  definition  in  the  specified  property  on  the 
named  window.  If  the  property  does  not  already  exist,  XSetRGBColormaps  sets  the  RGB 
colormap  definition  in  the  specified  property  on  the  named  window.  The  property  is  stored  with 
a  type  of  RGB_COLOR_MAP  and  a  format  of  32.  Note  that  it  is  the  caller's  responsibility  to  honor 
the  ICCCM  restriction  that  only  RGB_DEFAULT_MAP  contain  more  than  one  definition. 

XSetRGBColormaps  supersedes  XSetStandardColormap. 
For  more  information,  see  Volume  One,  Chapter  7,  Color. 

Structures 

typedef  struct  { 

Colormap  colormap; 
unsigned  long  red_max; 
unsigned  long  red_mult; 
unsigned  long  green_max; 
unsigned  long  green_mult; 
unsigned  long  blue_max; 
unsigned  long  blue  mult; 
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unsigned   long  base_jpixel; 

VisuallD   visualid;  /*    added  by   ICCCM  version    1    */ 

XID   killid;  /*   added  by   ICCCM  version   1    */ 

}    XStandardColormap; 

Errors 

BadAlloc 

BadAtom 

BadWindow 

Related  Commands 

XAllocStandardColormap, XGetRGBColormaps,  XVisuallDFromVisual. 
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•Xlib- Regions- 


Name 

XSetRegion  —  set  clip_mask  of  the  graphics  context  to  the  specified  region. 

Synopsis 

XSetRegion (display,  gc,  r) 
Display  *  display; 
GC  gc; 
Region  r; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

gc  Specifies  the  graphics  context. 

r  Specifies  the  region. 

Description 

XSetRegion  sets  the  clip_mask  component  of  a  GC  to  the  specified  region.  Thereafter,  all 
drawing  made  with  gc  will  be  confined  to  the  the  area  of  intersection  of  the  region  and  the 
drawable. 

Regions  are  located  using  an  offset  from  a  point  (the  region  origin)  which  is  common  to  all 
regions.  It  is  up  to  the  application  to  interpret  the  location  of  the  region  relative  to  a  drawable. 
When  the  region  is  to  be  used  as  a  clip_mask  by  calling  XSetRegion,  the  upper-left  corner 
of  region  relative  to  the  drawable  used  in  the  graphics  request  will  be  at  (xof  f  set  + 
clip_x_origin,  yof  f  set  +  clip_y_origin) ,  where  xof  f  set  and  yof  f  set  are 
the  offset  of  the  region  and  clip_x_origin  and  clip_y_origin  are  elements  of  the  GC 
used  in  the  graphics  request 

For  more  information  on  regions,  see  Volume  One,  Chapter  5,  The  Graphics  Context,  and 
Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox, XCreateRegion, XDestroyRegion, XEmptyRegion,  XEqualRegion, 
XIntersectRegion, XOf f setRegion,  XPointlnRegion,  XPolygonRegion, 
XRectlnRegion, XShrinkRegion, XSubtractRegion,  XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 
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— Xlib  -  Screen  Saver 

Name 

XSetScreenSaver  —  set  the  parameters  of  the  screen  saver. 

Synopsis 

XSetScreenSaver ( display,  timeout ,  interval , 

prefer_blanking,  allow_exposures) 
Display  *display; 
int  timeout,  interval; 
int  prefer_blanking; 
int  allov_exposures; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

timeout  Specifies  the  time  of  inactivity,  in  seconds,  before  the  screen  saver  turns  on. 

interval          Specifies  the  interval,  in  seconds,  between  screen  saver  invocations.  This  is 
for  intermittent  changes  to  the  display,  not  blanking. 

prefer_bl anking 

Specifies  whether  to  enable  screen  blanking.   Possible  values  are  Dont- 
Pref erBlanking,  Pref erBlanking,  or  Def aultBlanking. 

allow_exposures 

Specifies  the  current  screen  saver  control  values.  Possible  values  are  Dont- 
AllowExposures, AllowExposures,  or  Def aultExposures. 

Description 

XSetScreenSaver  sets  the  parameters  that  control  the  screen  saver,  timeout  and 
interval  are  specified  in  seconds.  A  positive  timeout  enables  the  screen  saver.  A 
timeout  of  zero  (0)  disables  the  screen  saver,  while  a  timeout  of  -1  restores  the  default.  An 
interval  of  zero  (0)  disables  the  random  pattern  motion.  If  no  input  from  devices  (key 
board,  mouse,  etc.)  is  generated  for  the  specified  number  of  timeout  seconds,  the  screen  saver  is 
activated. 

For  each  screen,  if  blanking  is  preferred  and  the  hardware  supports  video  blanking,  the  screen 
will  simply  go  blank.  Otherwise,  if  either  exposures  are  allowed  or  the  screen  can  be  regen 
erated  without  sending  exposure  events  to  clients,  the  screen  is  tiled  with  the  root  window 
background  tile,  with  a  random  origin,  each  interval  seconds.  Otherwise,  the  state  of  the 
screen  does  not  change.  All  screen  states  are  restored  at  the  next  input  from  a  device. 

If  the  server-dependent  screen  saver  method  supports  periodic  change,  interval  serves  as  a 
hint  about  how  long  the  change  period  should  be,  and  a  value  of  zero  (0)  hints  that  no  periodic 
change  should  be  made.  Examples  of  ways  to  change  the  screen  include  scrambling  the  color 
map  periodically,  moving  an  icon  image  about  the  screen  periodically,  or  tiling  the  screen  with 
the  root  window  background  tile,  randomly  reoriginated  periodically. 

For  more  information  on  the  screen  saver,  see  Volume  One,  Chapter  13,  Other  Programming 
Techniques. 
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Errors 

BadValue  timeout  <  -I. 

Related  Commands 

XActivateScreenSaver, XForceScreenSaver, XGetScreenSaver, XReset- 
ScreenSaver. 
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Name 

XSetSelectionOwner  —  set  the  owner  of  a  selection. 

Synopsis 

XSetSelectionOwner ( display,  selection,  owner,  time) 
Display  *display; 
Atom  selection; 
Window  owner; 
Time  time; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

selection       Specifies   the   selection    atom.    Predefined   atoms   are   XA  PRIMARY   and 

XA_SECONDARY. 

owner  Specifies  the  desired  owner  of  the  specified  selection  atom.  This  value  is 

either  a  window  ID  or  None. 

time  Specifies  the  time  when  the  selection  should  take  place.  Pass  either  a  times- 

tamp,  expressed  in  milliseconds,  or  the  constant  CurrentTime. 

Description 

XSetSelectionOwner  sets  the  owner  and  last-change  time  of  a  selection  property.  This 
should  be  called  by  an  application  that  supports  cutting  and  pasting  between  windows  (or  at 
least  cutting),  when  the  user  has  made  a  selection  of  any  kind  of  text,  graphics,  or  data.  This 
makes  the  information  available  so  that  other  applications  can  request  the  data  from  the  new 
selection  owner  using  xconvertselection,  which  generates  a  SeiectionRequest  event 
specifying  the  desired  type  and  format  of  the  data.  Then  the  selection  owner  sends  a 
SelectionNotify  using  xsendEvent,  which  notes  that  the  information  is  stored  in  the  selec 
tion  property  in  the  desired  format  or  indicates  that  it  couldn't  do  the  conversion  to  the  desired 
type. 

If  owner  is  specified  as  None,  then  this  client  is  giving  up  ownership  voluntarily.  Otherwise, 
the  new  owner  is  the  client  executing  the  request 

If  the  new  owner  is  not  the  same  as  the  current  owner  of  the  selection,  and  the  current  owner  is 
a  window,  then  the  current  owner  is  sent  a  SeiectionClear  event.  This  indicates  to  the  old 
owner  that  the  selection  should  be  unhighlighted. 

If  the  selection  owner  window  is  later  destroyed,  the  owner  of  the  selection  automatically 
reverts  to  None. 

The  value  you  pass  to  the  time  argument  must  be  no  earlier  than  the  last-change  time  of  the 
specified  selection,  and  no  later  than  the  current  time,  or  the  selection  is  not  affected.  The  new 
last-change  time  recorded  is  the  specified  time,  with  CurrentTime  replaced  by  the  current 
server  time.  If  the  X  server  reverts  a  selection  owner  to  None,  the  last-change  time  is  not 
affected. 

For  more  information  on  selections,  see  Volume  One,  Chapter  10, Inter client  Communication. 
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Errors 

BadAtom 
BadWindow 

Related  Commands 

XConve rt Select! on, XGet Select ionOwner. 
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Name 

XSetSizeHints  —  set  the  value  of  any  property  of  type  XA_SIZE_HINTS. 

Synopsis 

XSetSizeHints (display,  w,  hints,  property) 
Display  *display; 
Window  w; 

XSizeHints  *hints; 
Atom  property; 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi spl ay . 

v  Specifies  the  window  ID. 

hints  Specifies  a  pointer  to  the  size  hints. 

property         Specifies  the  property  atom. 

Description 

XSetSizeHints  has  been  superseded  by  XSetWMSizeHints  as  of  Release  4. 

XSetSizeHints  sets  the  named  property  on  the  specified  window  to  the  specified  XSize 
Hints  structure.  This  routine  is  useful  if  new  properties  of  type  XA_WM_SIZE_HINTS  are 
defined.  The  predefined  properties  of  that  type  have  their  own  set  and  get  functions,  XSet- 
NormalHints  and  XSetZoomHints  (XSetWMHints  in  Release  4 — zoom  hints  are  obso 
lete). 

The  flags  member  of  XSizeHints  must  be  set  to  the  OR  of  the  symbols  representing  each 
member  to  be  set 

For  more  information  on  using  hints,  see  Volume  One,  Chapter  IQJnterclient  Communication. 
Structures 

typedef  struct  { 

long  flags;    /*  which  fields  in  structure  are  defined  */ 

int  x,  y; 

int  width,  height; 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x;     /*  numerator  */ 

int  y;     /*  denominator  */ 
}  min_aspect,  max_aspect; 
}  XSizeHints; 

/*  flags  argument  in  size  hints  */ 

#define  USPosition  (1L  «  0)  /*  user  specified  x,  y  */ 

tdefine  USSize      (1L  «  1)  /*  user  specified  width,  height  */ 

#define  PPosition   (1L  «  2)  /*  program  specified  position  */ 

#define  PSize       (1L  «  3)  /*  program  specified  size  */ 
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tdefine  PMinSize    (1L  «  4)  /*  program  specified  minimum  size  */ 

tdefine  PMaxSize    (1L  «  5)  /*  program  specified  maximum  size  */ 

#define  PResizelnc  (1L  «  6)  /*  program  specified  resize  increments  */ 

tdefine  PAspect     (1L  «  7)  /*  program  specified  min/max  aspect  ratios  */ 

tdefine  PAllHints  (PPosit ion  I PSize I PMinSize I PMaxSize | PResizelnc | PAspect) 

Errors 

BadAlloc 

BadAtom 

BadWindow 

Related  Commands 

XFetchName,XGetClassHint,XGetIconName,XGetIconSizes,XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints,  XGetZoom- 
Hints,  XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet- 
NormalHints, XSetTransientForHint, XSetWMHints,  XSetZoomHints, 
XStoreName. 
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J  XSetStandardColormap 


Name 

XSetStandardColormap  —  change  the  standard  colormap  property. 

Synopsis 

void  XSetStandardColormap  ( display,  w,  cmap_info,  property) 
Display  * display; 
Window  w; 

XStandardColormap  *cmap_info; 
Atom  property; 

Arguments 

di spl ay         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi spl ay . 
w  Specifies  the  ID  of  the  window  with  which  this  colormap  will  be  associated. 

cmap_info    Specifies  the  filled  colormap  information  structure. 

property      Specifies  the  standard  colormap  property  to  set.  The  predefined  standard  color- 
maps  are:    XA_RGB_BEST_MAP,  XA_RGB_RED_MAP,  XA_RGB_GREEN_  MAP, 

XA_RGB_BLUE_MAP,  XA_RGB_DEFAULT_MAP,  and  XA_RGB_  GRAY_MAP. 

Description 

XSetStandardColormap  has  been  superseded  by  XSetRGBColormap  as  of  Release  4. 

XSetStandardColormap  defines  a  standard  colormap  property.  To  create  a  standard  color- 
map,  follow  this  procedure: 

1.  Open  a  new  connection  to  the  same  server. 

2.  Grab  the  server. 

3.  See  if  property  is  on  the  property  list  of  the  root  window  for  the  display,  using  XGet  - 
StandardColormap.  If  so,  see  if  the  colormap  field  is  nonzero.  If  it  is,  the  color- 
map  already  exists. 

4.  If  the  desired  property  is  not  present,  do  the  following: 

•  Determine  the  color  capabilities  of  the  display.  Choose  a  visual. 
Create  a  colormap  (not  required  for  XA_RGB_DEFAULT_MAP). 

Call  XAllocColorPlanes  or  XAllocColorCells  to  allocate  cells  in  the 
colormap. 

•  Call  xstoreColors  to  store  appropriate  color  values  in  the  colormap. 
Fill  in  the  descriptive  fields  in  the  structure. 

•  Call  XSetStandardColormap  to  set  the  property  on  the  root  window. 
Use  XSetCloseDownMode  to  make  the  resource  permanent. 

Close  the  new  connection  to  the  server. 
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(continued) 


Xlib  -  Colormaps 


5.  Ungrab  the  server. 

6.  Close  the  new  connection  to  the  server. 

See  description  of  standard  colormaps  in  Volume  One,  Chapter  7,  Color. 

Errors 

BadAlloc 

BadAtom 

BadWindow 


Structures 

typedef  struct  { 

Colormap  colormap; 

unsigned  long  red_max; 

unsigned  long  red_mult; 

unsigned  long  green_max; 

unsigned  long  green_mult, 

unsigned  long  blue_max; 

unsigned  long  blue_mult; 

unsigned  long  base_pixel, 
}  XStandardColormap; 


ID  of  colormap  made  by  XCreateColormap  */ 


/*  new  fields  in  R4  */ 


Related  Commands 

Def aultColormap,  DisplayCells, XCopyColormapAndFree, XCreate 
Colormap,  XFreeColormap, XGetStandardColormap,  XInstallColormap, 
XListlnstalledColormaps.XSetWindowColormap,  XUninstallColormap. 


470 


Xlib  Reference  Manual 
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Name 

XSetStandardProperties  —  set  the  minimum  set  of  properties  for  the  window  manager. 

Synopsis 

XSetStandardProperties ( display,  wf  window_name,  icon_name, 

icon_pixmap,  argv,  argc,  hints) 
Display  * display; 
Window  w; 

char  *window_name; 
char  *icon_name; 
Pixmap  icon_pixmap; 
char  **argv; 
int  argc; 
XSizeHints  *hints 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay . 

w  Specifies  the  window  ID. 

window_name  Specifies  the  name  of  the  window. 

i  con_name       Specifies  the  name  to  be  displayed  in  the  window's  icon. 

icon_pixmap  Specifies  the  pixmap  that  is  to  be  used  for  the  icon,  or  None.  This  pixmap 
must  be  of  depth  1. 

argv  Specifies  a  pointer  to  the  command  and  arguments  used  to  start  the  applica 

tion. 

argc  Specifies  the  number  of  arguments. 

hints  Specifies  a  pointer  to  the  size  hints  for  the  window  in  its  normal  state. 

Description 

XSetStandardProperties  is  superceded  by  XSetWMProperties  in  Release  4. 

XSetStandardProperties  sets  in  a  single  call  the  most  essential  properties  for  a  quickie 
application.  XSetStandardProperties  gives  a  window  manager  some  information  about 
your  program's  preferences;  it  probably  will  not  be  sufficient  for  complex  programs. 

See  Volume  One,  Chapter  10,  Interclient  Communication  for  a  description  of  standard  proper 
ties. 

Structures 

typedef  struct  { 

long  flags;  /*  which  fields  in  structure  are  defined  */ 

int  x,  y; 

int  width,  height; 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 
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struct  { 

int  x; 
int  y; 

}  min_aspect 
}  XSizeHints; 


/*  numerator  */ 
/*  denominator  */ 
max  aspect;     /*  new  fields  in  R4  */ 


/*  flags  argument  in  size  hints  */ 

#define  USPosition   (1L  «  O)/*  user  specified  x,  y  */ 

tdefine  USSize      (1L  «  I)/*  user  specified  width,  height  */ 


tdefine  PPosition 
#define  PSize 
#define  PMinSize 
#define  PMaxSize 
#define  PResizelnc 
#define  PAspect 


(1L  «  2) /*  program  specified  position  */ 

(1L  «  3)/*  program  specified  size  */ 

(1L  «  4)/*  program  specified  minimum  size  */ 

(1L  «  5)/*  program  specified  maximum  size  */ 

(1L  «  6) /*  program  specified  resize  increments  */ 

(1L  «  7)/*  program  specified  min  and  max  aspect  ratios  */ 


#define  PAllHints  (PPosition | PSize | PMinSize | PMaxSize | PResizelnc | PAspect) 

Errors 

BadAlloc 
BadWindow 

Related  Commands 

XChangeProperty, XDeleteProperty, XGetAtomName,  XGetFontProperty, 
XGetWindowProperty, XInternAtom,  XListProperties,  XRotateWindow- 
Properties. 


472 


Xlib  Reference  Manual 


-X,,b-Graph,cs  Context /  XSetState 

Name 

XSetState  —  set  the  foreground,  background,  logical  function,  and  plane  mask  in  a  graphics 
context. 

Synopsis 

XSetState  (display,  gc ,  foreground,  background,  function, 

plane_mask) 
Display  * display; 
GC  gc; 

unsigned  long  foreground,  background; 
int  function; 
unsigned  long  plane_mask; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

gc  Specifies  the  graphics  context. 

foreground  Specifies  the  foreground  for  the  specified  graphics  context. 

background  Specifies  the  background  for  the  specified  graphics  context. 

function  Specifies  the  logical  function  for  the  specified  graphics  context, 

pi ane_mask  Specifies  the  plane  mask  for  the  specified  graphics  context. 

Description 

XSetState  sets  the  foreground  and  background  pixel  values,  the  logical  function, 
and  the  plane_mask  in  a  GC.  See  XSetForeground,  XSetBackground,  XSet- 
Function,  and  XSetPlaneMask  for  what  these  members  do  and  appropriate  values. 

See  Volume  One,  Chapter  5,  The  Graphics  Context,  for  more  information. 
Errors 

BadGC 
BadValue 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode,  XSetBackground,  XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule,  XSetFillStyle,  XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane 
Mask,  XSetStipple, XSetSubwindowMode,  XSetTSOrigin. 
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XSetStipple  ~\ 


•Xlib- Graphics  Context- 


Name 

XSetStipple  —  set  the  stipple  in  a  graphics  context. 

Synopsis 

XSetStipple (display,  gc ,  stipple) 
Display  * display; 
GC  gc; 
Pixmap  stipple; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

gc  Specifies  the  graphics  context. 

stipple         Specifies  the  stipple  for  the  specified  graphics  context. 

Description 

XSetStipple  sets  the  stipple  component  of  a  GC.  The  stipple  is  a  pixmap  of  depth 
one.  It  is  laid  out  like  a  tile.  Set  bits  in  the  stipple  determine  which  pixels  in  an  area  are  drawn 
in  the  foreground  pixel  value.  Unset  bits  in  the  stipple  determine  which  pixels  are  drawn  in 
the  background  pixel  value  if  the  fill_style  is  FillOpaqueStippled.  If 
fill_style  is  FillStippled,  pixels  overlayed  with  unset  bits  in  the  stipple  are  not 
drawn.  If  f  ill_style  is  FillTiled  or  FillSolid,  the  stipple  is  not  used. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
Errors 

BadGC 

BadMatch 

BadPixmap 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask,  XSetClipOrigin,  XSetClip- 
Rectangles, XSetDashes, XSetFillRule,  XSetFillStyle,  XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane- 
Mask, XSetState, XSetSubwindowMode, XSetTSOrigin. 
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-x,,b  -  Graph.cs  con,«t XSetSubwindowMode 

Name 

XSetSubwindowMode  —  set  the  subwindow  mode  in  a  graphics  context. 

Synopsis 

XSetSubwindowMode (display,  gc ,  subwindow_mode) 
Display  * display; 
GC  gc  ; 
int  subwindow_mode ; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

gc  Specifies  the  graphics  context. 

subwindow_mode 

Specifies  the  subwindow  mode  you  want  to  set  for  the  specified  graphics  con 
text.  Possible  values  are  ClipByChildren  or  Includelnf  eriors. 

Description 

XSetSubwindowMode  sets  the  subwindow_mode  component  of  a  GC.  Clip 
ByChildren  means  that  graphics  requests  will  be  clipped  by  all  viewable  children. 
Includelnf  eriors  means  draw  through  all  subwindows. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
Errors 

BadGC 
BadValue 

Related  Commands 

Def aultGC, XChangeGC, XCopyGC,  XCreateGC, XFreeGC, XGContextFromGC, 
XSetArcMode, XSetBackground, XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule,  XSetFillStyle, XSetForeground, 
XSetFunction, XSetGraphicsExposures, XSetLineAttributes, XSetPlane- 
Mask, XSetState, XSetStipple,  XSetTSOrigin. 
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XSetTeXtPrOperty  \ x,,b -Window  Managers- 

Name 

XSetTextProperty  —  set  one  of  a  window's  text  properties. 
Synopsis 

void  XSetTextProperty  (display,  w,  text_prop,  property) 
Display  *  display; 
Window  w; 

XTextProperty  *text_prop; 
Atom  property; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window. 

text_prop       Specifies  the  XTextProperty  structure  to  be  used. 

property         Specifies  the  property  name. 

Availability 

Release  4  and  later. 

Description 

XSetTextProperty  sets  the  specified  property  for  the  named  window  with  the  data,  type, 
format,  and  number  of  items  determined  by  the  value  field,  the  encoding  field,  the  format 
field,  and  the  nitems  field,  respectively,  of  the  specified  XTextProperty  structure. 

Structures 

typedef  struct  { 

unsigned  char  *value;  /*  same  as  Property  routines  */ 

Atom  encoding;  /*  prop  type  */ 

int  format;  /*  prop  data  format:  8,  16,  or  32  */ 

unsigned  long  nitems;  /*  number  of  data  items  in  value  */ 
}  XTextProperty; 

Errors 

BadAlloc 
BadAtom 
BadValue 
BadWindow 

Related  Commands 

XFreeStringList,  XGetTextProperty,  XStringListToTextProperty,  XText- 
PropertytoStringList. 
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-Xllb  -  Plxmaps  and  Tiles '  XSetTHe 

Name 

XSetTile  —  set  the  fill  tile  in  a  graphics  context. 

Synopsis 

XSetTile (display,  gc ,  tile) 
Display  *  display; 
GC  gc; 
Pixmap  tile; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

gc  Specifies  the  graphics  context. 

tile  Specifies  the  desired  tile  for  the  specified  graphics  context. 

Description 

XSetTile  sets  the  tile  member  of  the  GC.  This  member  of  the  GC  determines  the  pixmap 
used  to  tile  areas.  The  tile  must  have  the  same  depth  as  the  destination  drawable.  This  tile  will 
only  be  used  in  drawing  if  the  fill-style  is  Fill  riled. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 
Errors 

BadGC 

BadMatch 

BadPixmap 

Related  Commands 

XCreateBitmapFromData,  XCreatePixmap,  XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile, 
XReadBitmapFile, XSetWindowBackgroundPixmap, XSetWindowBorder- 
Pixmap,  XWriteBitmapFile. 
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XSetTransientForHint  V X,ib- Window  Manager  H,ms- 

Name 

XSetTransientForHint  —  set  the  XA_WM_TRANSIENT_FOR  property  for  a  window. 

Synopsis 

XSetTransientForHint ( display,  w,  prop_window) 
Display  * display; 
Window  w; 
Window  prop_window; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID,  normally  of  a  dialog  box  popup. 

prop_window  Specifies  the  window  ID  that  the  XA_WM_TRANSIENT_FOR  property  is  to  be 
set  to.  This  is  usually  the  main  window  of  the  application. 

Description 

XSetTransientForHint  sets  the  XA_WM_TRANSIENT_FOR  property  of  the  specified  win 
dow.  This  should  be  done  when  the  window  w  is  a  temporary  child  (for  example,  a  dialog  box) 
and  the  main  top-level  window  of  its  application  is  prop_window.  Some  window  managers 
may  use  this  information  to  unmap  an  application's  dialog  boxes  (for  example,  when  the  main 
application  window  gets  iconified). 

For  more  information,  see  Volume  One,  Chapter  10, Inter -client  Communication. 
Errors 

BadAlloc 
BadWindow 

Related  Commands 

XFetchName, XGetClassHint, XGetlconName, XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints,  XGetZoom- 
Hints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet- 
NormalHints, XSetSizeHints, XSetWMHints, XSetZoomHints, XStoreName. 
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f  XSetTSOrigin 

— Xlib  -  Graphics  Context ' 

Name 

XSetTSOrigin  —  set  the  tile/stipple  origin  in  a  graphics  context. 

Synopsis 

XSetTSOrigin  ( display,  gc,  ts_x_originf  ts_y_origin) 
Display  * display ; 
GC  gc; 
int  ts_x_origin,  ts_y_origin; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenoisplay. 

gc  Specifies  the  graphics  context. 

ts_x_origin        Specify  the  x  and  y  coordinates  of  the  tile/stipple  origin. 

ts_y_ origin 

Description 

XSetTSOrigin  sets  the  ts_x_origin  and  ts_y_origin  components  in  a  GC,  which 
are  measured  relative  to  the  origin  of  the  drawable  specified  in  the  drawing  request  that  uses  the 
GC.  This  controls  the  placement  of  the  tile  or  the  stipple  pattern  that  patterns  an  area.  To  tile 
or  stipple  a  child  so  that  the  pattern  matches  the  parent,  you  need  to  subtract  the  current  posi 
tion  of  the  child  window  from  ts_x_ origin  and  ts_y_origin. 

For  more  information,  see  Volume  One,  Chapter  5,  The  Graphics  Context. 

Errors 

BadGC 

Related  Commands 

Def  aultGC,  XChangeGC,  XCopyGC,  XCreateGC,  XFreeGC,  XGContextFromGC, 
XSetArcMode,  XSetBackground,  XSetClipMask,  XSetClipOrigin, XSetClip- 
Rectangles, XSetDashes, XSetFillRule,  XSetFillStyle, XSetForeground, 
XSetFunction,  XSetGraphicsExposures, XSetLineAttributes, XSetPlane- 
Mask, XSetState, XSetStipple,  XSetSubwindowMode. 
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XSetWMCIientMachine  V xlib.wlndow  M,nager  «nu- 

Name 

XSetWMCIientMachine  —  set  a  window's  WM_CLIENT_MACHINE  property. 

Synopsis 

void  XSetWMCIientMachine  (display,  w,  text_prop) 
Display  *display; 
Window  w; 
XText Property  *text_prop; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window. 

text_jprop       Specifies  the  XText  Property  structure  to  be  used. 

Availability 

Release  4  and  later. 

Description 

XSetWMCIientMachine  performs  an  XSetTextProperty  to  set  the 
WM_CLIENT_MACHINE  property  of  the  specified  window.  This  property  should  contain  the 
name  of  the  host  machine  on  which  this  client  is  being  run,  as  seen  from  the  server. 

For  more  information,  see  Volume  One,  Chapter  10,  Interclient  Communication. 
Structures 

typedef  struct  { 

unsigned  char  *value;  /*  same  as  Property  routines  */ 

Atom  encoding;  /*  prop  type  */ 

int  format;  /*  prop  data  format:  8,  16,  or  32  */ 

unsigned  long  nitems;  /*  number  of  data  items  in  value  */ 
}  XTextProperty; 

Related  Commands 

XGetWMClientMachine. 
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— Xlib  -  Window  Manager  Hints - 


XSetWMColormapWindows 


Name 

XSetWMColormapWindows  —  set  a  window's  WM_COLORMAP_WINDOWS  property. 

Synopsis 

Status  XSetWMColormapWindows (display,  w,  colormap_windows , 

count) 

Display  * display; 
Window  w; 

Window  *colormap_windows ; 
int  count ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  window. 

col ormap_windows 

Specifies  the  list  of  windows. 

count  Specifies  the  number  of  windows  in  the  list. 

Availability 

Release  4  and  later. 

Description 

XSetWMColormapWindows  sets  the  WM_cOLORMAP_wiNDOWS  property  on  the  specified  win 
dow  to  the  list  of  windows  specified  by  the  colormap_windows  argument.  The  property  is 
stored  with  a  type  of  WINDOW  and  a  format  of  32.  If  it  cannot  intern  the 
WM_COLORMAP_WINDOWS  atom,  XSetWMColormapWindows  returns  a  zero  status.  Other 
wise,  it  returns  a  non-zero  status. 

This  property  tells  the  window  manager  that  subwindows  of  this  application  need  to  have  their 
own  colormaps  installed. 

For  more  information,  see  Volume  One,  Chapter  WJnterclient  Communication. 

Errors 

BadAlloc 
BadWindow 

Related  Commands 

XGetWMColormapWindows. 
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XSetWMIconName  V Xllb  _  Wlndow  Manager  Hlnts_ 

Name 

XSetWMIconName  —  set  a  window's  XA_WM_ICON_NAME  property. 

Synopsis 

void  XSetWMIconName  ( display  f  w,  text_prop) 
Display  ^display; 
Window  w; 
XTextProperty  *text_prop; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window. 

text_j>rop       Specifies  the  XTextProperty  structure  to  be  used. 

Availability 

Release  4  and  later. 

Description 

XSetWMIconName  performs  an  XSetTextProperty  to  set  the  XA_WM_ICON_NAME  prop 
erty  of  the  specified  window.  XSetWMIconName  supersedes  XSetlconName. 

This  is  usually  called  by  an  application  to  set  the  property  for  the  window  manager.  The  name 
should  be  short,  since  it  is  to  be  displayed  in  association  with  an  icon. 

XSetStandardProperties  (in  Release  4)  or  XSetWMProperties  (in  Release  4)  also 
set  this  property. 

For  more  information,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Structures 

typedef  struct  { 

unsigned  char  *value;  /*  same  as  Property  routines  */ 

Atom  encoding;  /*  prop  type  */ 

int  format;  /*  prop  data  format:  8,  16,  or  32  */ 

unsigned  long  nitems;  /*  number  of  data  items  in  value  */ 
}  XTextProperty; 

Related  Commands 

XGetWMIconName, XGetWMName, XSetWMName,  XSetWMProperties. 
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-X,,b  -Window  Manag.,  H,n, /  XSetWMName 

Name 

XSetWMName  —  set  a  window's  XA_WM_NAME  property. 

Synopsis 

void  XSetWMName  ( display,  w,  text_prop) 
Display  *  display; 
Window  w; 
XTextProperty  *text_propj 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  window. 

text_prop       Specifies  the  XTextProperty  structure  to  be  used. 

Availability 

Release  4  and  later. 

Description 

XSetWMName  performs  a  xsetTextProperty  to  set  the  XA_WM_NAME  property  on  the 
specified  window.  XSetWMName  supersedes  XStoreName.  This  property  can  also  be  set 
with  XSetWMProperties. 

XSetWMName  be  used  by  the  application  to  communicate  a  string  to  the  window  manager. 
According  to  current  conventions,  this  string  should  either: 

permit  the  user  to  identify  one  of  a  number  of  instances  of  the  same  client,  or 
provide  the  user  with  noncritical  state  information. 
Clients  can  assume  that  at  least  the  beginning  of  this  string  is  visible  to  the  user. 

The  XA_WM_CLASS  property,  on  the  other  hand,  has  two  members  which  should  be  used  to  iden 
tify  the  application's  instance  and  class  name,  for  the  lookup  of  resources.  See  XSetClass- 
Hint  for  details. 

For  more  information,  see  Volume  One,  Chapter  10,  Interclient  Communication. 


Structures 

typedef  struct  { 

unsigned  char  *value; 

Atom  encoding; 

int  format; 

unsigned  long  nitems; 
}  XTextProperty; 


/*  same  as  Property  routines  */ 

/*  prop  type  */ 

/*  prop  data  format:  8,  16,  or  32  */ 

/*  number  of  data  items  in  value  */ 


Related  Commands 

XGetWMIconName,  XGetWMName,  XSetWMIconName,  XSetWMProperties. 
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XSetWMNormalHints  V Xllb  _  Wlndow  Manager  Hlnts_ 

Name 

XSetWMNormalHints  —  set  a  window's  XA_WM_NORMAL_HINTS  property. 

Synopsis 

void  XSetWMNormalHints (display,  w,  hints) 
Display  *display; 
Window  w; 
XSizeHints  *hints; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD i  spl ay . 

w  Specifies  the  window. 

hints  Specifies  the  size  hints  for  the  window  in  its  normal  state. 

Availability 

Release  4  and  later. 

Description 

XSetWMNormalHints  sets  the  size  hints  in  the  XA_WM_NORMAL_HINTS  property  on  the 
specified  window.  The  property  is  stored  with  a  type  of  WM_SIZE_HINTS  and  a  format  of  32. 
XSetWMNormalHints  supersedes  XSetNormalHints.  This  property  can  also  be  set  with 
XSetWMProperties. 

Applications  use  XSetNormalHints  to  inform  the  window  manager  of  the  sizes  desirable 
for  that  window. 

To  set  size  hints,  an  application  must  assign  values  to  the  appropriate  elements  in  the  hints 
structure,  and  also  set  the  flags  field  of  the  structure  to  indicate  which  members  have 
assigned  values  and  the  source  of  the  assignment  These  flags  are  listed  in  the  Structures  sec 
tion  below. 

For  more  information,  see  Volume  One,  Chapter  10,  Interdient  Communication. 
Structures 

typedef  struct  { 

long  flags;        /*  marks  which  fields  in  this  structure  */ 

/*  are  defined  */ 

int  x,  y;          /*  obsolete  for  new  window  mgrs,  but  clients  */ 
int  width,  height;  /*  should  set  so  old  wm' s  don't  mess  up  */ 
int  min_width,  min_height; 
int  max_width,  max_height; 
int  width_inc,  height_inc; 
struct  { 

int  x;   /*  numerator  */ 

int  y;   /*  denominator  */ 
}  min_aspect,  max_aspect; 

int  base_width,  base_height;       /*  added  by  ICCCM  version  1  */ 
int  win_gravity;  /*  added  by  ICCCM  version  1  */ 
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Xlib  -  Window  Manager  Hints 


(continued) 


XSetWMNormalHints 


}  XSizeHints; 

#define  USPosition  (1L  «  0)  A 
tdefine  USSize     (1L  «  1)  A 


user  specified  x,  y  */ 

user  specified  width,  height  */ 


tdefine  PPosition  (1L  «  2)  /*  program  specified  position 


tdefine  PSize      (1L  «  3)  / 

tdefine  PMinSize   (1L  «  4)  / 

tdefine  PMaxSize   (1L  «  5)  / 

tdefine  PResizelnc  (1L  «  6)  / 


program  specified  size  V 
program  specified  minimum  size  */ 
program  specified  maximum  size  */ 
program  specified  resize  increments 


tdefine  PAspect    (1L  «  7)  /*  program  specified  min/max  aspect 
ratios  */ 

tdefine  PAllHints  (PPosition I PSize I PMinSize I PMaxSize I PResizelnc I PAspect) 
tdefine  PBaseSize  (1L  «  8)  /*  program  specified  base 

for  incrementing  */ 

tdefine  PWinGravity  (1L  «  9)/*  program  specified  window 

gravity   */ 

Errors 

BadAlloc 
BadWindow 

Related  Commands 

XGetWMNormalHints,  XSetWMProperties,  XSetWMSizeHints,  XGetWMSize- 
Hints. 
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XSetWMProperties 


•Xlib  -  Window  Manager  Hints- 


Name 

XSetWMProperties  —  set  a  window's  standard  window  manager  properties. 

Synopsis 

void  XSetWMProperties ( display,  w,  window_name ,  icon_name,  argvf 

argc ,  normal_hints ,  wm_hints,  class_hints) 
Display  *display; 
Window  w; 

XTextProperty  *window_name ; 
XTextProperty  *icon_name; 
char  **argv; 
int  argc; 

XSizeHints  *normal_hints ; 
XWMHints  *wm_hints; 
XClassHint  *class_hints ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window. 

window_name  Specifies  the  window  name,  which  should  be  a  null-terminated  string. 

i  con_name       Specifies  the  icon  name,  which  should  be  a  null-terminated  string. 

argv  Specifies  the  application's  argument  list. 

argc  Specifies  the  number  of  arguments . 

normal_hints 

Specifies  the  size  hints  for  the  window  in  its  normal  state. 

wm_hints         Specifies  the  XWMHints  structure  to  be  used. 
class_hints  Specifies  the  XClassHint  structure  to  be  used. 

Availability 

Release  4  and  later. 

Description 

XSetWMProperties  provides  a  single  programming  interface  for  setting  the  essential  win 
dow  properties  that  communicate  with  window  and  session  managers.  XSetWMProperties 
supersedes  XSetStandardProperties. 

If  the  window_name  argument  is  non-null,  XSetWMProperties  calls  XSetWMName, 
which,  in  turn,  sets  the  WM_NAME  property.  If  the  icon_name  argument  is  non-null,  XSet 
WMProperties  calls  xsetWMiconName,  which  sets  the  WM_ICON_NAME  property.  If  the 
argv  argument  is  non-null,  XSetWMProperties  calls  XSetCommand,  which  sets  the 
WM_COMMAND  property.  Note  that  an  argc  of  0  is  allowed  to  indicate  a  zero-length  command. 
XSetWMProperties  stores  the  hostname  of  this  machine  using  XSetWMClientMachine. 
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Xlib  -  Window  Manager  Hints  (continued)  XSetWMPropertieS 

If  the  normal_hints  argument  is  non-null,  XSetWMProperties  calls  XSetWMNormal- 
Hints,  which  sets  the  WM_NORMAL_HINTS  property.  If  the  wm_hints  argument  is  non-null, 
XSetWMProperties  calls  XSetWMHints,  which  sets  the  WM_HINTS  property. 

If  the  class_hints  argument  is  non-null,  XSetWMProperties  calls  XSetClassHint, 
which  sets  the  WM_CLASS  property.  If  the  res_name  member  in  the  XClassHint  structure 
is  set  to  the  null  pointer  and  the  RESOURCE_NAME  environment  variable  is  set,  then  value  of 
the  environment  variable  is  substituted  for  res_name.  If  the  res_name  member  is  NULL, 
and  if  the  environment  variable  is  not  set,  and  if  argvand  argv[0]  are  set,  then  the  value  of 
a rgv[ 0],  stripped  of  any  directory  prefixes,  is  substituted  for  res_name. 

For  more  information,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Structures 

typedef  struct  { 

unsigned  char  *value;  /*  same  as  Property  routines  */ 

Atom  encoding;  /*  prop  type  */ 

int  format;  /*  prop  data  format:  8,  16,  or  32  */ 

unsigned  long  nitems;  /*  number  of  data  items  in  value  */ 
}  XTextProperty; 

typedef  struct  { 

long  flags;      /*  marks  which  fields  in  this  structure  */ 
/*  are  defined  */ 

int  x,  y;        /*  obsolete  for  new  window  mgrs,  but  clients  */ 

int  width,  height;       /*  should  set  so  old  wm' s  don't  mess  up  */ 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x;   /*  numerator  */ 
int  y;   /*  denominator  */ 

}  min_aspect,  max_aspect; 

int  base_width,  base_height;     /*  added  by  ICCCM  version  1  */ 

int  win_gravity;  /*  added  by  ICCCM  version  1  */ 

}  XSizeHints; 

typedef  struct  { 

long  flags;      /*  marks  which  fields  in  this  structure  */ 

/*  are  defined  */ 
Bool  input;      /*  does  this  application  rely  on  the  window  */ 

/*  manager  to  get  keyboard  input?  */ 
int  initial_state;       /*  see  below  */ 

Pixmap  icon_pixmap;      /*  pixmap  to  be  used  as  icon  */ 
Window  icon_window;      /*  window  to  be  used  as  icon  */ 
int  icon_x,  icon_y;      /*  initial  position  of  icon  */ 
Pixmap  icon_mask;        /*  icon  mask  bitmap  */ 
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XID  window_group;       /*  id  of  related  window  group  */ 
/*  this  structure  may  be  extended  in  the  future  */ 
}  XWMHints; 

typedef  struct  { 

char  *res_name; 

char  *res_class; 
}  XClassHint; 

Errors 

BadAlloc 
BadWindow 

Related  Commands 

XGetClassHints,  XGetCommand,  XGetWMHints,  XGetWMIconName,  XGetWMName, 
XGetWMNormalHints,  XSetWMClientMachine,  XSetWMColormapWindows, XSet- 
WMProtocols. 
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J  XSetWMProtocols 

—  Xlib  -  Window  Manager  Hints ' 

Name 

XSetWMProtocols  —  set  a  window's  WM_PROTOCOLS  property. 

Synopsis 

Status  XSetWMProtocols  (display,  w,  protocols,  count) 
Display  ^display; 
Window  w; 
Atom  ^protocols; 
int  count; 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD i sp  1  ay . 

w  Specifies  the  window. 

protocols       Specifies  the  list  of  protocols. 

count  Specifies  the  number  of  protocols  in  the  list. 

Availability 

Release  4  and  later. 

Description 

XSetWMProtocols  sets  the  WM_PROTOCOLS  property  on  the  specified  window  to  the  list  of 
atoms  specified  by  the  protocols  argument.  The  property  is  stored  with  a  type  of  ATOM  and  a 
format  of  32.  If  it  cannot  intern  the  WM_PROTOCOLS  atom,  XSetWMProtocols  returns  a  zero 
status.  Otherwise,  it  returns  a  non-zero  status. 

The  list  of  standard  protocols  at  present  is  as  follows: 

WM_TAKE_FOCUS  Assignment  of  keyboard  focus 

WM_SAVE_YOURSELF  Save  client  state  warning 

WM_DELETE_UNKNOWN         Request  to  delete  top-level  window 

For  more  information,  see  Volume  One,  Chapter  10,  Interclient  Communication. 

Errors 

BadAlloc 
BadWindow 

Related  Commands 

XGetWMProtocols. 
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Name 

XSetWMSizeHints  —  set  a  window's  WM_SIZE_HINTS  property. 

Synopsis 

void  XSetWMSizeHints (display,  w,  hints,  property) 
Display  * display; 
Window  w; 

XSizeHints  *hints; 
Atom  property; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDi splay. 

w  Specifies  the  window. 

hints  Specifies  the  XSizeHints  structure  to  be  used. 

property         Specifies  the  property  name. 

Availability 

Release  4  and  later. 

Description 

XSetWMSizeHints  sets  the  size  hints  for  the  specified  property  on  the  named  window.  The 
property  is  stored  with  a  type  of  WM_SIZE_HINTS  and  a  format  of  32.  To  set  a  window's  nor 
mal  size  hints,  you  can  use  the  XSetWMNormalHints  function  instead.  XSetWMSize 
Hints  supersedes  XSetSizeHints. 

This  routine  is  useful  if  new  properties  of  type  XA_WM_SIZE_HINTS  are  defined. 

The  flags  member  of  XSizeHints  must  be  set  to  the  OR  of  the  symbols  representing  each 
member  to  be  set 

For  more  information,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Structures 

typedef  struct  { 

long  flags;      /*  marks  which  fields  in  this  structure  are  */ 

/*  defined  as  */ 

int  x,  y;       /*  obsolete  for  new  window  mgrs,  but  clients  */ 
int  width,  height;   /*  should  set  so  old  wm' s  don't  mess  up  */ 
int  min_width,  min_height; 
int  max_width,  max_height; 
int  width_inc,  height_inc; 
struct  { 

int  x;   /*  numerator  */ 

int  y;   /*  denominator  */ 
}  min_aspect,  max_aspect; 

int  base_width,  base_height;     /*  added  by  ICCCM  version  1  */ 
int  win_gravity;  /*  added  by  ICCCM  version  1  */ 
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(continued) 


XSetWMSizeHints 


}  XSizeHints; 

#define  USPosition  (1L  «  0) 
#define  USSize     (1L  «  1) 


user  specified  x,  y  */ 

user  specified  width,  height  */ 


#define  PPosition  (1L  «  2)  /*  program  specified  position 

*/ 

tdefine  PSize      (1L  «  3)  /*  program  specified  size  */ 

#define  PMinSize   (1L  «  4)  /*  program  specified  minimum  size  */ 

#define  PMaxSize   (1L  «  5)  /*  program  specified  maximum  size  */ 

#define  PResizelnc  (1L  «  6)  /*  program  specified  resize  increments  * 

#define  PAspect    (1L  «  7)  /*  program  specified  min/max  aspect 
ratios  */ 

#def ine  PAllHints  (PPosition | PSize I PMinSize I PMaxSize | PResizelnc I PAspect) 
tdefine  PBaseSize  (1L  «  8)  /*  program  specified  base 

for  incrementing  */ 
#define  PWinGravity  (1L  «  9)/*  program  specified  window 

gravity  */ 

Errors 

BadAlloc 

BadAtom 

BadWindow 

Related  Commands 

XAllocSizeHints,  XGetWMNormalHints,  XGetWMSizeHints,  XSetWMNormal- 
Hints. 
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XSetWindowBackground  \ 


•Xlib  -  Window  Attributes- 


Name 

XSetWindowBackground  —  set  the  background  pixel  value  attribute  of  a  window. 

Synopsis 

XSetWindowBackground ( display,  w,  background_pixel) 
Display  *  display; 
Window  w; 
unsigned  long  background_pixel ; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID.  Must  be  an  inputOutput  window. 

background_pixel 

Specifies  which  entry  in  the  colormap  is  used  as  the  background  color.  The 
constant  CopyFromParent  is  NOT  valid. 

Description 

XSetWindowBackground  sets  the  background  attribute  of  a  window,  setting  the  pixel 
value  to  be  used  to  fill  the  background.  This  overrides  any  previous  call  to  XSetWindow 
Background  or  XSetWindowBackgroundPixmap  on  the  same  window. 

XSetWindowBackground  does  not  change  the  current  window  contents  immediately.  The 
background  is  automatically  repainted  after  Expose  events.  You  can  also  redraw  the  back 
ground  without  Expose  events  by  calling  XClearWindow  immediately  after. 

For  more  information,  see  Volume  One,  Chapter  4,  Window  Attributes. 

Errors 

BadMatch          Setting  background  of  Input  Only  window. 

BadWindow 

Related  Commands 

XChangeWindowAttributes, XGet Geometry,  XGetWindowAttributes, XSet 
WindowBackgroundPixmap,  XSetWindowBorder,  XSetWindowBorderPixmap. 
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—  Xlib  -  Pixmaps  and  Tiles 

Name 

XSetWindowBackgroundPixmap  —  change  the  background  tile  attribute  of  a  window. 

Synopsis 

XSetWindowBackgroundPixmap (display,  w,  background_tile) 
Display  *display; 
Window  w; 
Pixmap  background_tile; 

Arguments 

di spl ay        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID.  Must  be  an  inputOutput  class  window. 

background_tile 

Specifies  a  pixmap  ID,  None  or  ParentRelative,  to  be  used  as  a  back 
ground. 

Description 

XSetWindowBackgroundPixmap  sets  the  background_pixmap  attribute  of  a  window. 
This  overrides  any  previous  background_pixel  or  background_pixmap  attribute  set 
ting  set  with  XSetWindowBackgroundPixmap,  XSetWindowBackground,  or 
XChangeWindowAttributes.  Drawing  into  the  pixmap  that  was  set  as  the  background 
pixmap  attribute  has  an  undefined  effect  on  the  window  background.  The  server  may  or  may 
not  make  a  copy  of  the  pixmap. 

If  the  background  is  set  to  a  pixmap,  the  background  is  tiled  with  the  pixmap.  If  the  pixmap  is 
not  explicitly  referenced  again,  it  can  be  freed,  since  a  copy  is  maintained  in  the  server.  The 
background  of  the  window  will  not  be  redrawn  with  the  new  tile  until  the  next  Expose  event 
or  XClearWindow  call. 

If  the  background  is  set  to  None,  The  window  background  initially  will  be  invisible  and  will 
share  the  bits  of  its  parent,  but  only  if  the  background_pixel  attribute  is  not  set.  When 
anything  is  drawn  by  any  client  into  the  area  enclosed  by  the  window,  the  contents  will  remain 
until  the  area  is  explicitly  cleared  with  XClearWindow.  The  background  is  not  automatically 
refreshed  after  exposure. 

If  the  background  is  set  to  ParentRelative,  the  parent's  background  is  used,  and  the  origin 
for  tiling  is  the  parent's  origin  (or  the  parent's  parent  if  the  parent's  background_pixmap 
attribute  is  also  ParentRelative,  and  so  on).  The  difference  between  setting  Parent- 
Relative  and  explicitly  setting  the  same  pixmap  as  the  parent  is  the  origin  of  the  tiling.  The 
difference  between  ParentRelative  and  None  is  that  for  ParentRelative  the  back 
ground  is  automatically  repainted  on  exposure. 

For  ParentRelative,  the  window  must  have  the  same  depth  as  the  parent,  or  a  BadMatch 
error  will  occur.  If  the  parent  has  background  None,  then  the  window  will  also  have  back 
ground  None.  The  parent's  background  is  re-examined  each  time  the  window  background  is 
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required  (when  it  needs  to  be  redrawn  due  to  mapping  or  exposure).  The  window's  contents 
will  be  lost  when  the  window  is  moved  relative  to  its  parent,  and  the  contents  will  have  to  be 
redrawn. 

Changing  the  background_pixmap  attribute  of  the  root  window  to  None  or  Parent- 
Relative  restores  the  default. 

XSetWindOwBackgroundPixmap  can  only  be  performed  on  an  Input  Output  window. 
A  BadMatch  error  will  result  otherwise. 

XSetwindowBackground  may  be  used  if  a  solid  color  instead  of  a  tile  is  desired. 
For  more  information,  see  Volume  One,  Chapter  4,  Window  Attributes. 

Errors 

BadMatch 

BadPixmap 

BadWindow 

Related  Commands 

XCreateBitmapFromData,  XCreatePixmap,  XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize, XQueryBestStipple, XQueryBestTile, 
XReadBitmapFile, XSetTile,  XSetWindowBorderPixmap, XWriteBitmapFile. 
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— Xlib  -  Window  Attributes ' 

Name 

XSetWindowBorder  —  change  a  window  border  pixel  value  attribute  and  repaint  the  border. 

Synopsis 

XSetWindowBorder (display,  w,  border^pixel) 
Display  * display ; 
Window  v, 
unsigned  long  border_pixel ; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  window  ID.  Must  be  an  inputOutput  window. 

border_pixel 

Specifies  the  colormap  entry  with  which  the  server  will  paint  the  border. 

Description 

XSetWindowBorder  sets  the  border _jpixel  attribute  of  window  w  to  a  pixel  value,  and 
repaints  the  border.  The  border  is  also  automatically  repainted  after  Expose  events. 

Use  XSetwindowBorderPixmap  to  create  a  tiled  border.  On  top-level  windows,  the  win 
dow  manager  often  resets  the  border,  so  applications  should  not  depend  on  their  settings. 

For  more  information,  see  Volume  One,  Chapter  4,  Window  Attributes. 

Errors 

BadMatch          Setting  border  of  inputOnly  window. 

BadWindow 

Related  Commands 

XChangeWindowAttributes, XGetGeometry,  XGetWindowAttributes, XSet- 
WindowBackground, XSetWindowBackgroundPixmap,  XSetwindowBorder 
Pixmap. 
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Name 

XSetWindowBorderPixmap  —  change  a  window  border  tile  attribute  and  repaint  the  border. 

Synopsis 

XSetWindowBorderPixmap (display,    w,    border_tile) 
Display    * display ; 
Window   w; 
Pixmap   jborder_tile; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

w  Specifies  the  ID  of  an  inputOutput  window  whose  border  is  to  be  to  a  file. 

border_tile  Specifies  any  pixmap  or  None. 

Description 

XSetWindowBorderPixmap  sets  the  border_pixmap  attribute  of  a  window  and  repaints 
the  border.  The  border_tile  can  be  freed  immediately  after  the  call  if  no  further  explicit 
references  to  it  are  to  be  made. 

This  function  can  only  be  performed  on  an  InputOutput  window.  On  top-level  windows, 
the  window  manager  often  resets  the  border,  so  applications  should  not  depend  on  their  set 
tings. 

Errors 

BadMatch 

BadPixmap 

BadWindow 

Related  Commands 

XCreateBitmapFromData,  XCreatePixmap,  XCreatePixmapFromBitmapData, 
XFreePixmap, XQueryBestSize,  XQueryBestStipple,  XQueryBestTile, 
XReadBitmapFile,  XSetTile,  XSetWindowBackgroundPixmap,  XWriteBitmap- 

File. 
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— Xlib  -  Window  Manipulation- 

Name 

XSetWindowBorderWidth  —  change  the  border  width  of  a  window. 

Synopsis 

XSetWindowBorderWidth  (display,  w,  width) 
Display  *display; 
Window  w; 
unsigned  int  width; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  whose  border  is  to  be  changed. 

wi  dth  Specifies  the  width  of  the  window  border. 

Description 

XSetWindowBorderWidth  changes  the  border  width  of  a  window.  This  request  is  often 
used  on  top-level  windows  by  the  window  manager  as  an  indication  of  the  current  keyboard 
focus  window,  so  other  clients  should  not  depend  on  the  border  width  of  top-level  windows. 

Errors 

BadMatch          Setting  border  width  of  an  Input  Only  window. 

BadWindow 

Related  Commands 

XCirculateSubwindows,  XCirculateSubwindowsDown, XCirculate- 
SubwindowsUp, XConf igureWindow,  XLowerWindow,  XMoveResizeWindow, 
XMoveWindow, XQueryTree,  XRaiseWindow,  XReparentWindow, XResize- 
Window,  XRestackWindows. 
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Name 

XSetWindowColormap  —  set  the  colormap  attribute  for  a  window. 

Synopsis 

XSetWindowColormap ( display,  wr  cmap) 
Display  * display; 
Window  w; 
Colormap  cmap; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  for  which  you  want  to  set  the  colormap. 

cmap  Specifies  the  colormap. 

Description 

XSetWindowColormap  sets  the  colormap  attribute  of  the  specified  window.  The  color- 
map  need  not  be  installed  to  be  set  as  an  attribute,  cmap  will  be  used  to  translate  pixel  values 
drawn  into  this  window  when  cmap  is  installed  in  the  hardware,  which  will  be  taken  care  of  by 
the  window  manager. 

In  Release  3,  applications  must  install  their  own  colormaps  if  they  cannot  use  the  default  color- 
map.  In  Release  4,  they  should  never  do  so. 

The  colormap  must  have  the  same  visual  as  the  window. 

Errors 

BadColormap 

BadMatch 

BadWindow 

Related  Commands 

XChangeWindowAttributes, XGetGeometry,  XGetWindowAttributes, XSet- 
WindowBackground,  XSetWindowBackgroundPixmap,  XSetWindowBorder, 
XSetWindowBorderPixmap,  XSetWMColormapWindows. 
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Name 

XSetWMHintS  —  set  a  window  manager  hints  property. 

Synopsis 

XSetWMHintS  (display,  w,  wmhints) 
Display  * display; 
Window  w; 
XWMHints  *  wmhints; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  xopenDi splay. 

w  Specifies  the  ID  for  which  window  manager  hints  are  to  be  set. 

wmh ints         Specifies  a  pointer  to  the  window  manager  hints. 

Description 

XSetWMHintS  sets  the  window  manager  hints  that  include  icon  information  and  location,  the 
initial  state  of  the  window,  and  whether  the  application  relies  on  the  window  manager  to  get 
keyboard  input. 

This  function  is  unnecessary  in  Release  4  if  you  call  XSetWMProperties. 

See  Volume  One,  Chapter  10,  Interclient  Communication,  for  a  description  of  each  XWMHints 
structure  member. 

Structures 

typedef  struct  { 

long  flags;  /*  marks  defined  fields  in  structure  */ 

Bool  input;  /*  does  application  need  window  manager  for 

*  keyboard  input  */ 

int  initial_state;    /*  see  below  */ 

Pixmap  icon_pixmap;   /*  pixmap  to  be  used  as  icon  */ 

Window  icon_window;   /*  window  to  be  used  as  icon  */ 

int  icon_x,  icon_y;   /*  initial  position  of  icon  */ 

Pixmap  icon_mask;     /*  icon  mask  bitmap  */ 

XID  window_group;     /*  ID  of  related  window  group  */ 

/*  this  structure  may  be  extended  in  the  future  */ 
}  XWMHints; 

/*  definitions  for  the  flags  field:  */ 
#define  InputHint  (1L  «  0) 
#define  StateHint  (1L  «  1) 
#define  IconPixmapHint  (1L  «  2) 
fdefine  IconWindowHint  (1L  «  3) 
#define  IconPositionHint  (1L  «  4) 
tdefine  IconMaskHint  (1L  «  5) 
#define  WindowGroupHint  (1L  «  6) 

#define  AllHints  (InputHint | StateHint | IconPixmapHint | IconWindowHint |  \ 
IconPositionHint I IconMaskHint I WindowGroupHint) 
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/*  definitions  for  the  initial  state  flag:  */ 


#define  DontCareState  0 

#define  NormalState  1 

#define  ZoomState  2 

#define  IconicState  3 

#define  InactiveState  4 


/*  don't  know  or  care  */ 

/*  most  applications  want  to  start  this  way 
/*  application  wants  to  start  zoomed  */ 
/*  application  wants  to  start  as  an  icon  */ 
/*  application  believes  it  is  seldom  used; 
some  wm' s  may  put  it  on  inactive  menu  */ 


Errors 

BadAlloc 
BadWindow 

Related  Commands 

XAllocWMHints, XFetchName,  XGetClassHint,  XGetlconName,  XGetlcon- 
Sizes, XGetNormalHints,  XGetSizeHints,  XGetTransientForHint, XGet- 
WMHints,  XGetZoomHints,  XSetClassHint,  XSetCommand.  XSetlconName, 
XSetlconSizes, XSetNormalHints,  XSetSizeHints,  XSetTransientForHint, 
XSetZoomHints, XStoreName,  XSetWMProperties. 
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Name 

XSetZoomHints  —  set  the  size  hints  property  of  a  zoomed  window. 

Synopsis 

XSetZoomHints  ( display,  w,  zhints) 
Display  * display; 
Window  w; 
XSizeHints  * zhints; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  for  which  zoom  hints  are  to  be  set. 

zhints  Specifies  a  pointer  to  the  zoom  hints. 

Description 

XSetZoomHints  is  no  longer  used  as  of  Release  3. 

XSetZoomHints  sets  the  XA_WM_ZOOM_HINTS  property  for  an  application's  top-level  win 
dow  in  its  zoomed  state.  Many  window  managers  think  of  windows  in  three  states:  iconified, 
normal,  or  zoomed,  corresponding  to  small,  medium,  and  large.  Applications  use  XSetZoom 
Hints  to  inform  the  window  manager  of  the  size  or  position  desirable  for  the  zoomed  window. 

In  addition,  an  application  wanting  to  move  or  resize  its  zoomed  window  should  call  XSet 
ZoomHints  specifying  its  new  desired  location  and  size,  in  addition  to  making  direct  X  calls 
to  move  or  resize.  This  is  because  some  window  managers  may  redirect  window  configuration 
requests,  but  ignore  the  resulting  events  and  pay  attention  to  property  changes  instead. 

To  set  size  hints,  an  application  must  assign  values  to  the  appropriate  elements  in  the  hints 
structure,  and  set  the  flags  field  of  the  structure  to  indicate  which  members  have  assigned 
values  and  the  source  of  the  assignment.  These  flags  are  listed  in  the  Structures  section  below. 

For  more  information  on  using  hints,  see  Volume  One,  Chapter  WJnterclient  Communication. 
Structures 

typedef  struct  { 

long  flags;  /*  marks  defined  fields  in  structure  */ 

int  x,  y; 

int  width,  height; 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x;  /*  numerator  */ 

int  y;  /*  denominator  */ 

}  min_aspect,  max_aspect; 

/*  new  fields  in  R4  */ 
}  XSizeHints; 
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XSetZoom Hints  (continued)  Xlib  -  Window  Manager  Hints 

/*  flags  argument  in  size  hints  */ 

tdefine  USPosition  (IL  «  0)   /*  user  specified  x,  y  */ 

#define  USSize      (IL  «  1)   /*  user  specified  width,  height  */ 

#define  PPosition  (IL  «  2)  /*  program  specified  position  */ 

#define  PSize  (IL  «  3)  /*  program  specified  size  */ 

#define  PMinSize  (IL  «  4)  /*  program  specified  minimum  size  */ 

#define  PMaxSize  (IL  «  5)  /*  program  specified  maximum  size  */ 

#define  PResizelnc  (IL  «  6)  /*  program  specified  resize  increments  */ 

#define  PAspect  (IL  «  7)  /*  program  specified  min/max  aspect  ratios  */ 
#define  PAH Hints  (PPosition | PSize | PMinSize | PMaxSize | PResizelnc | PAspect) 

Errors 

BadAlloc 
BadWindow 

Related  Commands 

XFetchName, XGetClassHint, XGetlconName,  XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints,  XSetClassHint,  XSetCoinmand,  XSetlconName,  XSetlconSizes,  XSet- 
NormalHints, XSetSizeHints,  XSetTransientForHint,  XSetWMHints, 
XStoreName. 
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f  XShrinkRegion 

—  Xlib  -  Regions ' 

Name 

XShrinkRegion  —  reduce  or  expand  the  size  of  a  region. 

Synopsis 

XShrinkRegion  ( r,    dx,    dy) 
Region    r; 
int    dx,    dy; 

Arguments 

r  Specifies  the  region. 

dx  Specify  the  amounts  by  which  you  want  to  shrink  or  expand  the  specified 

dy  region.   Positive  values  shrink  the  region  while  negative  values  expand  the 

region. 

Description 

XShrinkRegion  changes  the  width  and/or  height  of  the  specified  region.  Positive  values 
shrink  the  region;  negative  values  expand  the  region.  It  is  legal  to  expand  the  region  in  one 
dimension  at  the  same  time  as  shrinking  it  in  the  other  dimension.  The  offset  of  the  region  is 
changed  to  keep  the  center  of  the  resized  region  near  its  original  position. 

The  exact  amount  of  shrinkage  for  a  given  value  for  dx  or  dy  is  not  specified  by  Xlib. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion, XDestroyRegion,  XEmptyRegion,  XEqualRegion, 
XIntersectRegion, XOf f setRegion,  XPointlnRegion,  XPolygonRegion, 
XRectlnRegion,  XSetRegion,  XSubtractRegion,  XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 
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XStoreBuffer  \ V1 

v Xlib  -  Cut  Buffers— 

Name 

XStoreBuffer  —  store  data  in  a  cut  buffer. 

Synopsis 

XStoreBuffer ( display,  bytes,  nbytes ,  buffer) 
Display  * display ; 
char  bytes [ ] ; 
int  nbytes; 
int  buffer; 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

bytes  Specifies  the  string  of  bytes  you  want  stored.  The  byte  string  is  not  necessarily 

ASCII  or  null-terminated. 

nbytes          Specifies  the  number  of  bytes  in  the  string. 

buffer          Specifies  the  cut  buffer  in  which  to  store  the  byte  string.  Must  be  in  the  range 
0-7. 

Description 

XStoreBuffer  stores  the  specified  data  into  any  one  of  the  eight  cut  buffers.  All  eight  buf 
fers  must  be  stored  into  before  they  can  be  circulated  with  XRotateBuf  f  ers.  The  cut  buf 
fers  are  numbered  0  through  7.  Use  XFetchBuf  f  er  to  recover  data  from  any  cut  buffer. 

Note  that  selections  are  the  preferred  method  of  transferring  data  between  applications. 

For  more  information  on  cut  buffers,  see  Volume  One,  Chapter  13,  Other  Programming  Tech 
niques.  For  more  information  on  selections,  see  Volume  One,  Chapter  10,  Inter  client  Commu 
nication. 

Errors 

BadAlloc 
BadAtom 

Related  Commands 

XFetchBuf fer, XFetchBytes,  XRotateBuf f ers, XStoreBytes. 
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f~  XStoreBytes 

— Xlib  -  Cut  Buffers ' 

Name 

XStoreBytes  —  store  data  in  cut  buffer  0. 

Synopsis 

XStoreBytes (display,  bytes,  nbytes) 
Display  * display; 
char  bytes[] ; 
int  nbytes; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

bytes  Specifies  the  string  of  bytes  to  store.  The  byte  string  is  not  necessarily  ASCII  or 

null-terminated. 

nbytes  Specifies  the  number  of  bytes  to  store. 

Description 

XStoreBytes  stores  data  in  cut  buffer  0,  usually  for  reading  by  another  client  that  already 
knows  the  meaning  of  the  contents.  Note  that  the  cut  buffer's  contents  need  not  be  text,  so  null 
bytes  are  not  special. 

The  cut  buffer's  contents  may  be  retrieved  later  by  any  client  calling  XFetchBytes. 

Use  XStoreBuf fer  to  store  data  in  buffers  1-7.  Note  that  selections  are  the  preferred 
method  of  transferring  data  between  applications. 

For  more  information  on  cut  buffers,  see  Volume  One,  Chapter  13,  Other  Programming  Tech 
niques.  For  more  information  on  selections,  see  Volume  One,  Chapter  10,  Inter  client  Commu 
nication. 

Errors 

BadAlloc 

Related  Commands 

XFetchBuf f er, XFetchBytes, XRotateBuf f ers, XStoreBuf fer. 


Xlib  Reference  Manual  505 


XStoreColor  X X|lb  _  ^  Ce||s_ 

Name 

XStoreColor  —  set  or  change  the  RGB  values  of  a  read/write  colormap  entry  to  the  closest  pos 
sible  hardware  color. 

Synopsis 

XStoreColor ( display,  cmap,  colorcell_def) 
Display  *display; 
Colormap  cmap; 
XColor  *colorcell_def; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

cmap  Specifies  the  colormap. 

col  orcell_def     Specifies  a  pixel  value  and  the  desired  RGB  values. 

Description 

XStoreColor  changes  the  RGB  values  of  a  colormap  entry  specified  by 
col orcell_def. pixel  to  the  closest  values  possible  on  the  hardware.  This  pixel  value 
must  be  a  read/write  cell  and  a  valid  index  into  cmap.  XStoreColor  changes  the  red,  green, 
and/or  blue  color  components  in  the  cell  according  to  the  colorcell_def  .flags  member, 
which  you  set  by  ORing  the  constants  DoRed,  DoGreen,  and/or  DoBlue. 

If  the  colormap  is  an  installed  map  for  its  screen,  the  changes  are  visible  immediately. 
For  more  information,  see  Volume  One,  Chapter  7,  Color. 

Structures 

typedef   struct    { 

unsigned   long  pixel; 

unsigned   short    red,    green,    blue; 

char    flags;  /*    DoRed,    DoGreen,    DoBlue    */ 

char  pad; 
}    XColor; 

Errors 

BadAccess        A  specified  pixel  is  unallocated  or  read-only. 

BadColormap 

BadValue          pixel  not  valid  index  into  cmap. 

Related  Commands 

BlackPixel, WhitePixel, XAllocColor,  XAllocColorCells, XAllocColor- 
Planes, XAllocNamedColor, XFreeColors,  XLookupColor,  XParseColor, 
XQueryColor, XQueryColors, XStoreColors,  XStoreNamedColor. 
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—Xlib -Color  Cells- 


J  XStoreColors 


Name 

XStoreColors  —  set  or  change  the  RGB  values  of  read/write  colorcells  to  the  closest  possible 
hardware  colors. 

Synopsis 

XStoreColors ( display,  cmap ,  colorcell_defs ,  ncolors) 
Display  * display; 
Colormap  cmap; 

XColor  colorcell_defs [ncolors] ; 
int  ncolors; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

cmap  Specifies  the  colormap. 

colorcell_defs 

Specifies  an  array  of  color  definition  structures. 

ncolors         Specifies  the  number  of  XColor  structures  in  colorcell_defs. 

Description 

XStoreColors  changes  the  RGB  values  of  each  colormap  entry  specified  by  color- 
cell_defs []  .pixel  to  the  closest  possible  hardware  colors.  Each  pixel  value  must  be  a 
read/write  cell  and  a  valid  index  into  cmap.  XStoreColors  changes  the  red,  green,  and/or 
blue  color  components  in  each  cell  according  to  the  colorcell_def s  [ ]  .flags  member, 
which  you  set  by  ORing  the  constants  DoRed,  DoGreen,  and/or  DoBlue.  The  specified  pix 
els  are  changed  if  they  are  writable  by  any  client,  even  if  one  or  more  pixels  generates  an  error. 

If  the  colormap  is  an  installed  map  for  its  screen,  the  changes  are  visible  immediately.  For 
more  information,  see  Volume  One,  Chapter  7,  Color. 

Structures 

typedef    struct    { 

unsigned   long  pixel; 

unsigned   short    red,    green,    blue; 

char    flags;  /*    DoRed,    DoGreen,    DoBlue    */ 

char  pad; 
}    XColor; 

Errors 

BadAcce  s  s        A  specified  pixel  is  unallocated  or  read-only. 

BadColormap 

BadValue          A  specified  pixel  is  not  a  valid  entry  into  cmap. 

Related  Commands 

BlackPixel, WhitePixel, XAllocColor,  XAllocColorCells, XAllocColor- 
Planes, XAllocNamedColor, XFreeColors,  XLookupColor,  XParseColor, 
XQueryColor, XQueryColors,  XStoreColor,  XStoreNamedColor. 
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XStoreName  V Xlib  _  Window  Manager  Hlnts_ 

Name 

XStoreName  —  assign  a  name  to  a  window  for  the  window  manager. 

Synopsis 

XStoreName  ( display ,  wr  window_name) 
Display  * display; 
Window  w; 
char  *window_name ; 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  to  which  you  want  to  assign  a  name. 

window_name  Specifies  the  name  of  the  window.  The  name  should  be  a  null-terminated 
string.  This  name  is  returned  by  any  subsequent  call  to  XFetchName. 

Description 

XStoreName  is  superceded  in  Release  4  by  XSetWMName. 

XStoreName  sets  the  XA_WM_NAME  property,  which  should  be  used  by  the  application  to  com 
municate  the  following  information  to  the  window  manager,  according  to  current  conventions: 

To  permit  the  user  to  identify  one  of  a  number  of  instances  of  the  same  client. 
To  provide  the  user  with  noncritical  state  information. 
Clients  can  assume  that  at  least  the  beginning  of  this  string  is  visible  to  the  user. 

The  XA_WM_CLASS  property,  on  the  other  hand,  has  two  members  which  should  be  used  to  iden 
tify  the  application's  instance  and  class  name,  for  the  lookup  of  resources.  See  XSetClass- 
Hint  for  details. 

For  more  information,  see  Volume  One,  Chapter  10,  Inter -client  Communication. 

Errors 

BadAlloc 
BadWindow 

Related  Commands 

XFetchName, XGetClassHint, XGetlconName,  XGetlconSizes, XGetNormal- 
Hints, XGetSizeHints, XGetTransientForHint, XGetWMHints, XGetZoom- 
Hints, XSetClassHint, XSetCommand, XSetlconName, XSetlconSizes, XSet- 
NormalHints, XSetSizeHints,  XSetTransientForHint,  XSetWMHints,  XSet- 
ZoomHints. 
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-x,ib- wmdow  Manager  H.ms '  XStoreNamedColor 

Name 

XStoreNamedColor  —  set  RGB  values  of  a  read/write  colorcell  by  color  name. 

Synopsis 

XStoreNamedColor (display,  cmap,  colorname,  pixel,  flags) 
Display  *display, 
Co lo rmap  cmap ; 
char  * colorname; 
unsigned  long  pixel; 
int  flags; 

Arguments 

display         Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

cmap  Specifies  the  colormap. 

colorname  Specifies  the  color  name  string  (for  example,  "red").  This  cannot  be  in  hex  for 
mat  (as  used  in  XParseColor).  Upper  or  lower  case  is  not  important.  The 
string  should  be  in  ISO  LATIN- 1  encoding,  which  means  that  the  first  128  char 
acter  codes  are  ASCII,  and  the  second  128  character  codes  are  for  special  char 
acters  needed  in  western  languages  other  than  English. 

pixel  Specifies  the  entry  in  the  colormap  to  store  color  in. 

flags  Specifies  which  red,  green,  and  blue  indexes  are  set. 

Description 

XStoreNamedColor  looks  up  the  named  color  in  the  database,  with  respect  to  the  screen 
associated  with  cmap,  then  stores  the  result  in  the  read/write  colorcell  of  cmap  specified  by 
pixel.  Upper  or  lower  case  in  name  does  not  matter.  The  flags  argument,  a  bitwise  OR  of 
the  constants  DoRed,  DoGreen,  and  DoBlue,  determines  which  subfields  within  the  pixel 
value  in  the  cell  are  written. 

For  more  information,  see  Volume  One,  Chapter  7,  Color. 

Errors 

BadAccess        pixel  is  unallocated  or  read-only. 

BadColormap 

BadName  col  orname  is  not  in  server's  color  database. 

BadValue          pixel  is  not  a  valid  index  into  cmap. 

Related  Commands 

Def aultColormap, DisplayCells,  XCopyColormapAndFree, XCreate- 
Colormap, XFreeColormap,  XGetStandardColormap,  XInstallColormap, 
XListInstalledColormaps,XSetStandardColormap, XSetWindowColormap, 
XUninstallColormap. 
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XStringListToTextProperty  \ XMb.wlndowManager  Hints_ 

Name 

XStringListToTextProperty  —  set  the  specified  list  of  strings  to  an  XTextProperty  struc 
ture. 

Synopsis 

Status  XStringListToTextProperty (list,  count,  text^prop) 
char  **list; 
int  count ; 
XTextProperty  *text_prop;     /*  RETURN  */ 

Arguments 

list  Specifies  a  list  of  null-terminated  character  strings. 

count  Specifies  the  number  of  strings. 

text_jDrop       Returns  the  XTextProperty  structure. 

Availability 

Release  4  and  later. 

Description 

XStringListToTextProperty  fills  the  specified  XTextProperty  structure  so  that  it 
represents  a  property  of  type  STRING  (format  8)  with  a  value  representing  the  concatenation  of 
the  specified  list  of  null-separated  character  strings.  An  extra  byte  containing  NULL  (which  is 
not  included  in  the  nit  ems  member)  is  stored  at  the  end  of  the  value  field  of  text_prop. 
If  insufficient  memory  is  available  for  the  new  value  string,  XStringListToText 
Property  does  not  set  any  fields  in  the  XTextProperty  structure  and  returns  a  zero  status. 
Otherwise,  it  returns  a  non-zero  status.  To  free  the  storage  for  the  value  field,  use  XFree. 

For  more  information,  see  Volume  One,  Chapter  IQJnterclient  Communication. 
Structures 

typedef  struct  { 

unsigned  char  *value;  /*  same  as  Property  routines  */ 

Atom  encoding;  /*  prop  type  */ 

int  format;  /*  prop  data  format:  8,  16,  or  32  */ 

unsigned  long  nitems;  /*  number  of  data  items  in  value  */ 
}  XTextProperty; 

Related  Commands 

XSetTextProperty,  XGetTextProperty,  XTextPropertyToStringList, 
XFreeStringList. 
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-«*  -  Keyboard /  XStringToKeysym 

Name 

XStringToKeysym  —  convert  a  keysym  name  string  to  a  keysym. 

Synopsis 

KeySym  XStringToKeysym  ( string) 
char  *string; 

Arguments 

string  Specifies  the  name  of  the  keysym  that  is  to  be  converted. 

Description 

XStringToKeysym  translates  the  character  string  version  of  a  keysym  name  ("Shift")  to  the 
matching  keysym  which  is  a  constant  (XK_Shift).  Valid  keysym  names  are  listed  in 
<Xll/keysymdef.h>.  If  the  specified  string  does  not  match  a  valid  keysym,  XString 
ToKeysym  returns  NoSymbol. 

This  string  is  not  the  string  returned  in  the  buffer  argument  of  XLookupSt  r ing,  which  can 
be  set  with  XRebindKeysym.  If  that  string  is  used,  XStringToKeysym  will  return  No- 
Symbol  except  by  coincidence. 

In  Release  4,  XStringToKeysym  can  return  keysyms  that  are  not  defined  by  the  Xlib  stan 
dard.  Note  that  the  set  of  keysyms  that  are  available  in  this  manner  and  the  mechanisms  by 
which  Xlib  obtains  them  is  implementation  dependent.  (In  the  MIT  sample  implementation, 
the  resource  file  lusrlliblXHIXKeysymDB  is  used  starting  in  Release  4.  The  keysym  name  is 
used  as  the  resource  name,  and  the  resource  value  is  the  keysym  value  in  uppercase  hexade 
cimal.) 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
Related  Commands 

XChangeKeyboardMapping,  XDeleteModif iermapEntry, XFreeModif iermap, 
XGetKeyboardMapping,  XGetModif ierMapping,  XInsertModif iermapEntry, 
XKeycodeToKeysym,  XKeysymToKeycode,  XKeysymToString,  XLookupKeysym, 
XLookupString, XNewModif ierMap, XQueryKeymap,  XRebindKeysym, 
XRefreshKeyboardMapping,  XSetModif ierMapping. 
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XSublmage  \ X(|b  _  lmages_ 

Name 

XSublmage  —  create  a  subimage  from  part  of  an  image. 

Synopsis 

Xlmage    *XSub Image  (ximage,    x,    y,    subimage_width,    subimage_height) 
Xlmage    * ximage; 
int    x;y; 
unsigned  int    subimage_width ;  subimage_height ; 

Arguments 

ximage      Specifies  a  pointer  to  the  image. 

x  Specify  the  x  and  y  coordinates  in  the  existing  image  where  the  subimage  will  be 

y  extracted. 

s  ubima  ge_wi  dt  h 
subimage_height 

Specify  the  width  and  height  (in  pixels)  of  the  new  subimage. 

Description 

XSublmage  creates  a  new  image  that  is  a  subsection  of  an  existing  one.  It  allocates  the  mem 
ory  necessary  for  the  new  Xlmage  structure  and  returns  a  pointer  to  the  new  image.  The  data 
is  copied  from  the  source  image,  and  the  rectangle  defined  by  x,  y,  subimage_width,  and 
subimage_height  must  by  contained  in  the  image. 

XSublmage  extracts  a  subimage  from  an  image,  while  XGet  Sub  Image  extracts  an  image 
from  a  drawable. 

For  more  information  on  images,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
Related  Commands 

ImageByteOrder,  XAddPixel,  XCreatelmage,  XDestroy Image,  XGetlmage, 
XGetPixel,  XGet Sub Image, XPut Image,  XPutPixel. 
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J  XSubtractRegion 

— Xlib  -  Regions ' 

Name 

XSubtractRegion  —  subtract  one  region  from  another. 

Synopsis 

XSubtractRegion  (sra,    srb,    dr) 
Region   sra,    srb; 
Region   dr;  /*  RETURN    */ 

Arguments 

sra  Specify  the  two  regions  in  which  you  want  to  perform  the  computation. 

srb 

dr  Returns  the  result  of  the  computation. 

Description 

XSubtractRegion  calculates  the  difference  between  the  two  regions  specified  (sra  -  srb) 
and  puts  the  result  in  dr. 

This  function  returns  a  region  which  contains  all  parts  of  sra  that  are  not  also  in  srb. 
For  more  information  on  regions,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion,  XDestroyRegion,  XEmptyRegion,  XEqualRegion, 
XIntersectRegion, XOf f setRegion, XPointlnRegion,  XPolygonRegion, 
XRectlnRegion,  XSetRegion,  XShrinkRegion,  XUnionRectWithRegion, 
XUnionRegion, XXorRegion. 
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XSync 


Xlib-  Output  Buffer- 


Name 

XSync  —  flush  the  request  buffer  and  wait  for  all  events  and  errors  to  be  processed  by  the 
server. 

Synopsis 

XSync (display,  discard) 
Display  *  display; 
int  discard; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

discard  Specifies  whether  XSync  discards  all  events  on  the  input  queue.  This  argu 

ment  is  either  True  or  False. 

Description 

XSync  flushes  the  request  buffer,  then  waits  until  all  events  and  errors  resulting  from  previous 
calls  have  been  received  and  processed  by  the  X  server.  Events  are  placed  on  the  input  queue. 
The  client's  XError  routine  is  called  once  for  each  error  received. 

If  discard  is  True,  XSync  discards  all  events  on  the  input  queue  (including  those  events  that 
were  on  the  queue  before  XSync  was  called). 

XSync  is  sometimes  used  with  window  manipulation  functions  (by  the  window  manager)  to 
wait  for  all  resulting  exposure  events.  Very  few  clients  need  to  use  this  function. 

Related  Commands 

XFlush. 
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J  XSynchronize 

— Xlib  -  Input  Handling ' 

Name 

XSynchronize  —  enable  or  disable  synchronization  for  debugging. 

Synopsis 

int    (*XSynchronize ( display,    onoff))  () 
Display   * display ; 
Bool    onoff; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

onoff  Specifies  whether  to  enable  or  disable  synchronization.  You  can  pass  False 

(normal  asynchronous  mode)  or  True  (enable  synchronization  for  debug 
ging). 

Description 

XSynchronize  turns  on  or  off  synchronous  mode  for  debugging.  If  onoff  is  True,  it  turns 
on  synchronous  behavior;  False  resets  the  state  to  normal  mode. 

When  events  are  synchronized,  they  are  reported  as  they  occur  instead  of  at  some  later  time,  but 
server  performance  is  many  times  slower.  This  can  be  useful  for  debugging  complex  event 
handling  routines.  Under  UNIX,  the  same  result  can  be  achieved  without  hardcoding  by  setting 
the  global  variable  _xdebug  to  True  from  within  a  debugger. 

XSynchronize  returns  the  previous  after  function. 

For  more  information,  see  Volume  One,  Chapter  3,  Basic  Window  Program. 

Related  Commands 

QLength,  XAllowEvents,  XChecklf  Event,  XCheckMaskEvent,  XCheckTyped- 
Event, XCheckTypedWindowEvent, XCheckWindowEvent, XEventsQueued, 
XGetlnputFocus, XGetMotionEvents, Xlf Event,  XMaskEvent, XNextEvent, 
XPeekEvent, XPeeklf Event, XPending,  XPutBackEvent, XSelectlnput, 
XSendEvent,  XSetlnputFocus, XWindowEvent. 
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XTextExtents  \ Xlib  _  Text_ 

Name 

XTextExtents  —  get  string  and  font  metrics  locally. 

Synopsis 

XTextExtents (font_struct ,    string,    nchars ,    direction, 

ascent,    descent,    overall) 
XFontStruct    *font_struct ; 
char   *string; 
int   nchars; 

int    * direction;  /*  RETURN    */ 

int   *  ascent,    *descent;  /*  RETURN   */ 

XCharStruct    *  overall;  /*  RETURN    */ 

Arguments 

f  ont_struct  Specifies  a  connection  to  an  XFontStruct  structure. 

string  Specifies  the  character  string  for  which  metrics  are  to  be  returned. 

nchars  Specifies  the  number  of  characters  in  the  character  string. 

direction       Returns  the  value  of  the  direction  element  of  the  XFontStruct.  Either 
Font Right ToLef t or  FontLef tToRight. 

ascent  Returns  the  font  ascent  element  of  the  XFontStruct.  This  is  the  overall 

maximum  ascent  for  the  font 

descent  Returns  the  font  descent  element  of  the  XFontStruct.  This  is  the  overall 

maximum  descent  for  the  font 

overall  Returns  the  overall  characteristics  of  the  string.  These  are  the  sum  of  the 

width  measurements  for  each  character,  the  maximum  ascent  and 
descent,  the  minimum  Ibearing  added  to  the  width  of  all  characters  up 
to  the  character  with  the  smallest  Ibearing,  and  the  maximum  rbearing 
added  to  the  width  of  all  characters  up  to  the  character  with  the  largest 
rbearing. 

Description 

XTextExtents  returns  the  dimensions  in  pixels  that  specify  the  bounding  box  of  the  speci 
fied  string  of  characters  in  the  named  font,  and  the  maximum  ascent  and  descent  for  the  entire 
font  This  function  performs  the  size  computation  locally  and,  thereby,  avoids  the  roundtrip 
overhead  of  XQueryTextExtents,  but  it  requires  a  filled  XFontStruct. 

ascent  and  descent  return  information  about  the  font,  while  overall  returns  information 
about  the  given  string.  The  returned  ascent  and  descent  should  usually  be  used  to  calcu 
late  the  line  spacing,  while  the  width,  rbearing,  and  Ibearing  members  of  overall 
should  be  used  for  horizontal  measures.  The  total  height  of  the  bounding  rectangle,  good  for 
any  string  in  this  font,  is  ascent  +  descent. 

overall .  ascent  is  the  maximum  of  the  ascent  metrics  of  all  characters  in  the  string.  The 
overall .  descent  is  the  maximum  of  the  descent  metrics.  The  overall .  width  is  the 
sum  of  the  character-width  metrics  of  all  characters  in  the  string.  The  overall .  Ibearing 
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Xlib  -  Text 


(continued) 


XTextExtents 


is  the  Ibearing  of  the  character  in  the  string  with  the  smallest  Ibearing  plus  the  width  of 
all  the  characters  up  to  but  not  including  that  character.  The  overall .  rbearing  is  the 
rbearing  of  the  character  in  the  string  with  the  largest  rbearing  plus  the  width  of  all  the 
characters  up  to  but  not  including  that  character. 

For  more  information  on  drawing  text,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and 
Text. 


Structures 

typedef  struct  { 

XExtData  *ext_data;  /* 

Font  fid;  /* 

unsigned  direction;  /* 
unsigned  min_char_or_byte2;  /* 
unsigned  max_char_or_byte2; /* 

unsigned  min  bytel;  /* 

unsigned  max_bytel;  /* 

Bool  all_chars_exist;  /* 

unsigned  default  char;  /* 

int  n_properties;  /* 

XFontProp  *properties;  /* 

XCharStruct  min  bounds;  /* 

XCharStruct  max_bounds;  /* 

XCharStruct  *per_char;  /* 

int  ascent;  /* 

int  descent;  /* 

}  XFontStruct; 


hook,  for  extension  to  hang  data  */ 

font  ID  for  this  font  */ 

hint  about  direction  the  font  is  painted  */ 

first  character  */ 

last  character  */ 

first  row  that  exists  */ 

last  row  that  exists  */ 

flag  if  all  characters  have  nonzero  size*/ 

char  to  print  for  undefined  character  */ 

how  many  properties  there  are  */ 

pointer  to  array  of  additional  properties*/ 

minimum  bounds  over  all  existing  char*/ 

minimum  bounds  over  all  existing  char*/ 

first_char  to  last_char  information  */ 

logical  extent  above  baseline  for  spacing  */ 

logical  descent  below  baseline  for  spacing  */ 


typedef  struct  { 

short  Ibearing; 

short  rbearing; 

short  width; 

short  ascent; 

short  descent; 

unsigned  short  attributes; 
}  XCharStruct; 


/*  origin  to  left  edge  of  character  */ 

/*  origin  to  right  edge  of  character  */ 

/*  advance  to  next  char's  origin  */ 

/*  baseline  to  top  edge  of  character  */ 

/*  baseline  to  bottom  edge  of  character 

/*  per  char  flags  (not  predefined)  */ 


*/ 


Related  Commands 

XDrawImageString, XDrawImageStringl6,XDrawString, XDrawStringlG, 
XDrawText, XDrawTextl6,  XQueryTextExtents,  XQueryTextExtentsl6, 
XTextExtent si 6, XTextWidth,  XTextWidthl 6. 
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XTextExtentsI  6  \ Xllb  _  Text_ 

Name 

XTextExtentsl6  —  get  string  and  font  metrics  of  a  16-bit  character  string,  locally. 

Synopsis 

XTextExtentsI 6 (font_struct ,    string,    nchars,    direction, 

ascent,    descent,    overall) 
XFontStruct    *font_struct ; 
XChar2b   *string; 
int    nchars; 

int    *  direction;  /*  RETURN    */ 

int    *  ascent,    *  descent;  /*  RETURN    */ 

XCharStruct    *  overall;  /*  RETURN    */ 

Arguments 

font_struct  Specifies  a  connection  to  an  XFontStruct  structure. 

string  Specifies  the  character  string  made  up  of  XChar2  6  structures. 

nchars  Specifies  the  number  of  characters  in  the  character  string. 

direction       Returns  the  value  of  the  direction  element  of  the  XFontStruct.  Font- 
RightToLeft  of  FontLeftToRight. 

ascent  Returns  the  font  ascent  element  of  the  XFontStruct.  This  is  the  overall 

maximum  ascent  for  the  font. 

descent  Returns  the  font  descent  element  of  the  XFontStruct.  This  is  the  overall 

maximum  descent  for  the  font. 

overall  Returns  the  overall  characteristics  of  the  string.  These  are  the  sum  of  the 

width  measurements  for  each  character,  the  maximum  ascent  and 
descent,  the  minimum  Ibearing  added  to  the  width  of  all  characters  up 
to  the  character  with  the  smallest  Ibearing,  and  the  maximum  rbearing 
added  to  the  width  of  all  characters  up  to  the  character  with  the  largest 
rbearing. 

Description 

XTextExtentsI 6  returns  the  dimensions  in  pixels  that  specify  the  bounding  box  of  the 
specified  string  of  characters  in  the  named  font,  and  the  maximum  ascent  and  descent  for  the 
entire  font.  This  function  performs  the  size  computation  locally  and,  thereby,  avoids  the 
roundtrip  overhead  of  XQueryTextExtentsl  6,  but  it  requires  a  filled  XFontStruct. 

ascent  and  descent  return  information  about  the  font,  while  overall  returns  information 
about  the  given  string.  The  returned  ascent  and  descent  should  usually  be  used  to  calcu 
late  the  line  spacing,  while  the  width,  rbearing,  and  Ibearing  members  of  overall 
should  be  used  for  horizontal  measures.  The  total  height  of  the  bounding  rectangle,  good  for 
any  string  in  this  font,  is  ascent  +  descent. 

overall .  ascent  is  the  maximum  of  the  ascent  metrics  of  all  characters  in  the  string.  The 
overall .  descent  is  the  maximum  of  the  descent  metrics.  The  overall .  width  is  the 
sum  of  the  character-width  metrics  of  all  characters  in  the  string.  The  overall .  Ibearing 
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Xlib-Text 


(continued) 


XTextExtents16 


is  the  Ibearing  of  the  character  in  the  string  with  the  smallest  Ibearing  plus  the  width  of 
all  the  characters  up  to  but  not  including  that  character.  The  overall .  rbearing  is  the 
rbearing  of  the  character  in  the  string  with  the  largest  rbearing  plus  the  width  of  all  the 
characters  up  to  but  not  including  that  character. 

For  more  information  on  drawing  text,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and 
Text. 


Structures 

typedef  struct  { 

short  Ibearing; 

short  rbearing; 

short  width; 

short  ascent; 

short  descent; 

unsigned  short  attributes; 
}  XCharStruct; 

typedef  struct  { 

XExtData  *ext_data; 

Font  fid; 

unsigned  direction; 

unsigned  min_char_or_byte2; 

unsigned  max_char_or_byte2; 

unsigned  min_bytel; 

unsigned  max_bytel; 

Bool  all_chars_exist; 

unsigned  default  char; 

int  n_properties; 

XFontProp  *properties; 

XCharStruct  min_bounds; 

XCharStruct  max_bounds; 

XCharStruct  *per_char; 

int  ascent; 

int  descent; 
}  XFontStruct; 

typedef  struct  { 

unsigned  char  bytel; 
unsigned  char  byte2; 

}  XChar2b; 


/*  origin  to  left  edge  of  character  */ 

/*  origin  to  right  edge  of  character  */ 

/*  advance  to  next  char's  origin  */ 

/*  baseline  to  top  edge  of  character  */ 

/*  baseline  to  bottom  edge  of  character 

/*  per  char  flags  (not  predefined)  */ 


/*  hook  for  extension  to  hang  data  */ 

/*  font  ID  for  this  font  */ 

/*  hint  about  direction  the  font  is  painted  */ 

/*  first  character  */ 

/*  last  character  */ 

/*  first  row  that  exists  */ 

/*  last  row  that  exists  */ 

/*  flag  if  all  characters  have  nonzero  size*/ 

/*  char  to  print  for  undefined  character  */ 

/*  how  many  properties  there  are  */ 

/*  pointer  to  array  of  additional  properties*/ 

/*  minimum  bounds  over  all  existing  char*/ 

/*  minimum  bounds  over  all  existing  char*/ 

/*  first_char  to  last_char  information  */ 

/*  logical  extent  above  baseline  for  spacing  */ 

/*  logical  descent  below  baseline  for  spacing  */ 


/*  normal  16  bit  characters  are  two  bytes  */ 


Related  Commands 

XDrawImageString, XDrawImageStringl6,XDrawString,  XDrawStringlS, 
XDrawText, XDrawText 1 6,  XQueryTextExtent s,  XQueryTextExtent si  6, 
XTextExtents, XTextWidth, XTextWidthl6. 
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XTextPropertyToStringList  \ X|ib.  Wlndow  Manager  Hints_ 

Name 

XTextPropertyToStringList  —  obtain  a  list  of  strings  from  a  specified  XText Property  struc 
ture. 

Synopsis 

Status  XTextPropertyToStringList (text_propf  list,  count) 
XTextProperty  *text_prop; 
char  ***list;     /*  RETURN  */ 
int  *  count;       /*  RETURN  */ 

Arguments 

text_prop       Specifies  the  XTextProperty  structure  to  be  used. 

list  Returns  a  list  of  null-terminated  character  strings. 

count  Returns  the  number  of  strings. 

Availability 

Release  4  and  later. 

Description 

XTextPropertyToStringList  returns  a  list  of  strings  representing  the  null-separated 
elements  of  the  specified  XTextProperty  structure.  The  data  in  text_prop  must  be  of 
type  STRING  and  format  8.  Multiple  elements  of  the  property  (for  example,  the  strings  in  a  dis 
joint  text  selection)  are  separated  by  a  NULL  (encoding  0).  The  contents  of  the  property  are  not 
null-terminated.  If  insufficient  memory  is  available  for  the  list  and  its  elements,  XText 
PropertyToStringList  sets  no  return  values  and  returns  a  zero  status.  Otherwise,  it 
returns  a  non-zero  status.  To  free  the  storage  for  the  list  and  its  contents,  use  XFreeSt ring- 
List. 

For  more  information,  see  Volume  One,  Chapter  10,  Inter -client  Communication. 
Structures 

typedef  struct  { 

unsigned  char  *value;  /*  same  as  Property  routines  */ 

Atom  encoding;  /*  prop  type  */ 

int  format;  /*  prop  data  format:  8,  16,  or  32  */ 

unsigned  long  nitems;  /*  number  of  data  items  in  value  */ 
}  XTextProperty; 

Related  Commands 

XFreeStringList.  XGetTextProperty,  XSetTextProperty,  XStringListTo- 
TextProperty. 
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f  XTextWidth 

— Xlib  -  Text ' 

Name 

XTextWidth  —  get  the  width  in  pixels  of  an  8-bit  character  string,  locally. 

Synopsis 

int  XTextWidth (font_struct ,  string,  count) 
XFontStruct  *font_struct; 
char  *string; 
int  count; 

Arguments 

font_struct  Specifies  the  font  description  structure  of  the  font  in  which  you  want  to  draw 
the  string. 

string  Specifies  the  character  string  whose  width  is  to  be  returned. 

count  Specifies  the  character  count  in  s t r i n g. 

Description 

XTextWidth  returns  the  width  in  pixels  of  the  specified  string  using  the  specified  font  This 
is  the  sum  of  the  XCharSt  ruct .  width  for  each  character  in  the  string.  This  is  also  equiva 
lent  to  the  value  of  overall,  width  returned  by  XQueryTextExtents  or  XText- 
Extents.  The  calculation  is  done  assuming  8-bit  font  indexing. 

For  more  information  on  drawing  text,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and 
Text. 

Structures 

typedef  struct  { 

XExtData  *ext_data;  /*  hook  for  extension  to  hang  data  */ 

Font  fid;  /*  font  ID  for  this  font  */ 

unsigned  direction;  /*  hint  about  direction  the  font  is  painted  */ 

unsigned  min_char_or_byte2; /*  first  character  */ 

unsigned  max_char_or_byte2; /*  last  character  */ 

unsigned  min_bytel;  /*  first  row  that  exists  */ 

unsigned  max_bytel;  /*  last  row  that  exists  */ 

Bool  all_chars_exist;  /*  flag  if  all  characters  have  nonzero  size*/ 

unsigned  default_char;  /*  char  to  print  for  undefined  character  */ 

int  n_properties;  /*  how  many  properties  there  are  */ 

XFontProp  ^properties;  /*  pointer  to  array  of  additional  properties*/ 

XCharStruct  min_bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  max_bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  *per_char;  /*  first_char  to  last_char  information  */ 

int  ascent;  /*  logical  extent  above  baseline  for  spacing  */ 

int  descent;  /*  logical  descent  below  baseline  for  spacing  */ 

}  XFontStruct; 

Related  Commands 

XDrawImageString, XDrawImageStringl6,XDrawString,  XDrawStringlS, 
XDrawText, XDrawTextl6,  XQueryTextExtents,  XQueryTextExtentsl 6, 
XTextExtents,XTextExtentsl6,XTextWidthl6. 
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XTextWidth16  \ XHb.Text_ 

Name 

XTextWidthl6  —  get  the  width  in  pixels  of  a  16-bit  character  string,  locally. 

Synopsis 

int  XTextWidthl6 (font_struct ,  string,  count) 
XFontStruct  *font_struct  ; 
XChar2b  *string; 
int  count; 

Arguments 

font_struct  Specifies  the  font  description  structure  of  the  font  in  which  you  want  to  draw 
the  string. 

string  Specifies  a  character  string  made  up  of  XChar2b  structures, 

count  Specifies  the  character  count  in  s  t  ri  n  g. 

Description 

XTextwidthl6  returns  the  width  in  pixels  of  the  specified  string  using  the  specified  font. 
This  is  the  sum  of  the  XCharStruct  .width  for  each  character  in  the  string.  This  is  also 
equivalent  to  the  value  of  overall .  width  returned  by  XQueryTextExtentsl6  or 
XTextExtentsl6. 

The  calculation  is  done  assuming  16-bit  font  indexing. 

For  more  information  on  drawing  text,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and 
Text. 

Structures 

typedef  struct  { 

XExtData  *ext_data;  /*  hook  for  extension  to  hang  data  */ 

Font  fid;  /*  font  ID  for  this  font  */ 

unsigned  direction;  /*  hint  about  direction  the  font  is  painted  */ 

unsigned  min_char_or_byte2;  /*  first  character  */ 

unsigned  max_char_or_byte2;  /*  last  character  */ 

unsigned  min_bytel;  /*  first  row  that  exists  */ 

unsigned  max_bytel;  /*  last  row  that  exists  */ 

Bool  all_chars_exist;  /*  flag  if  all  characters  have  nonzero  size*/ 

unsigned  default_char;  /*  char  to  print  for  undefined  character  */ 

int  n_properties;  /*  how  many  properties  there  are  */ 

XFontProp  *properties;  /*  pointer  to  array  of  additional  properties*/ 

XCharStruct  min_bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  max_bounds;  /*  minimum  bounds  over  all  existing  char*/ 

XCharStruct  *per_char;  /*  first_char  to  last_char  information  */ 

int  ascent;  /*  logical  extent  above  baseline  for  spacing  */ 

int  descent;  /*  logical  descent  below  baseline  for  spacing  */ 

}  XFontStruct; 

Related  Commands 

XDrawImageString,  XDrawImageStringl6,XDrawString,  XDrawStringlS, 

XDrawText,XDrawTextl6,XQueryTextExtents,XQueryTextExtentsl6, 

XTextExtents,XTextExtentsl6,XTextWidth. 
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j  XTranslateCoordinates 

— Xlib  -  Standard  Geometry ' 

Name 

XTranslateCoordinates  —  change  the  coordinate  system  from  one  window  to  another. 

Synopsis 

Bool  XTranslateCoordinates (display,  src_w,  frame_w,  src_xf 

src_y,  new_x,  new_y,  child) 
Display  *  display; 
Window  src_wr  frame_w; 
int  src_xf  src_y; 

int   *new_x,    *nevr_y;  /*  RETURN   */ 

Window   * chi Id;  /*  RETURN   */ 

Arguments 

display        Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

src_w  Specifies  the  ID  of  the  source  window. 

frame_w        Specifies  the  ID  of  the  frame  of  reference  window. 

src_x  Specify  the  x  and  y  coordinates  within  the  source  window. 

src_y 

new_x  Return  the  translated  x  and  y  coordinates  within  the  frame  of  reference  window. 

new_y 

child  If  the  point  is  contained  in  a  mapped  child  of  the  destination  window,  then  that 

child  ID  is  returned  in  child. 

Description 

XTranslateCoordinates  translates  coordinates  from  the  frame  of  reference  of  one  win 
dow  to  another. 

XTranslateCoordinates  returns  False  and  *new_x  and  *new_y  are  set  to  zero  if 
src_w  and  frame_w  are  on  different  screens.  In  addition,  if  the  coordinates  are  contained  in 
a  mapped  child  of  frame_w,  then  that  child  is  returned  in  the  child  argument  When  src_w 
and  frame_y  are  on  the  same  screen,  XTranslateCoordinates  returns  True,  sets 
*new_x  and  *new_y  to  the  location  of  the  point  relative  to  f~rame_w,  and  sets  child  to 
None. 

This  should  be  avoided  in  most  applications  since  it  requires  a  roundtrip  request  to  the  server. 
Most  applications  benefit  from  the  window-based  coordinate  system  anyway  and  don't  need 
global  coordinates.  Window  managers  often  need  to  perform  a  coordinate  transformation  from 
the  coordinate  space  of  one  window  to  another,  or  unambiguously  determine  which  subwindow 
a  coordinate  lies  in.  XTranslateCoordinates  fulfills  this  need,  while  avoiding  any  race 
conditions  by  asking  the  server  to  perform  this  operation. 

Errors 

BadWindow 

Related  Commands 

XGeometry, XParseGeometry. 
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XUndefineCursor  \ Vl 

v Xhb  -  Cursors- 
Name 

XUndefineCursor  —  disassociate  a  cursor  from  a  window. 

Synopsis 

XUndefineCursor  (display,    w) 
Display   *  display; 
Window    w; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD i  spl  ay . 

w  Specifies  the  ID  of  the  window  whose  cursor  is  to  be  undefined. 

Description 

XUndefineCursor  sets  the  cursor  attribute  for  a  window  to  its  parent's  cursor,  undoing  the 
effect  of  a  previous  XDef  ineCursor  for  this  window.  On  the  root  window  the  default  cursor 
is  restored. 

Errors 

BadWindow 

Related  Commands 

XCreateFontCursor, XCreateGlyphCursor,  XCreatePixmapCursor, XDef ine 
Cursor,  XFreeCursor, XQueryBestCursor,  XQueryBestSize, XRecolor- 
Cursor. 
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J  XUngrabButton 

— Xlib  -  Grabbing ' 

Name 

XUngrabButton  —  release  a  button  from  a  passive  grab. 

Synopsis 

XUngrabButton  (display,  button,  modifiers,  w) 
Display  *display; 
unsigned  int  button; 
unsigned  int  modifiers; 
Window  w; 

Arguments 

display  Specifies  a  connection  to  an  X  server,  returned  from  XOpenDisplay. 

button  Specifies  the  mouse  button  to  be  released  from  grab.   Specify  Buttonl, 

Button2,  Buttons,  Button4,  Buttons,  or  the  constant  AnyButton, 
which  is  equivalent  to  issuing  the  ungrab  request  for  all  possible  buttons. 

modifiers  Specifies  a  set  of  keymasks.  This  is  a  bitwise  OR  of  one  or  more  of  the  fol 
lowing  symbols:  ShiftMask,  LockMask,  ControlMask,  ModlMask, 
Mod2Mask,  ModSMask,  Mod4Mask,  ModSMask,  or  AnyModifier. 
AnyModif  ier  is  equivalent  to  issuing  the  ungrab  button  request  for  all  pos 
sible  modifier  combinations  (including  no  modifiers). 

w  Specifies  the  ID  of  the  window  you  want  to  release  the  button  grab. 

Description 

XUngrabButton  cancels  the  passive  grab  on  a  button/key  combination  on  the  specified  win 
dow  if  it  was  grabbed  by  this  client.  A  modifiers  of  AnyModifier  is  equivalent  to  issu 
ing  the  ungrab  request  for  all  possible  modifier  combinations  (including  the  combination  of  no 
modifiers).  A  button  of  AnyButton  is  equivalent  to  issuing  the  request  for  all  possible  but 
tons.  This  call  has  no  effect  on  an  active  grab. 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
Errors 

BadWindow 

BadValue          Invalid  button  or  modifiers  mask. 

Related  Commands 

XChangeActivePointerGrab,  XGrabButton,  XGrabKey,  XGrabKeyboard, 
XGrabPointer, XGrabServer, XUngrabKey,  XUngrabKeyboard,  XUngrab- 
Pointer,  XUngrabServer. 


Xlib  Reference  Manual  525 


XUngrabKey  \ 


•Xlib- Grabbing  — 


Name 

XUngrabKey  —  release  a  key  from  a  passive  grab. 

Synopsis 

XUngrabKey (display,  keycode,  modifiers,  w) 
Display  * display; 
int  keycode; 
unsigned  int  modifiers; 
Window  w; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

keycode  Specifies  the  keycode.  This  keycode  maps  to  the  specific  key  you  want  to 

ungrab.  Pass  either  a  keycode  or  AnyKey. 

modifiers  Specifies  a  set  of  keymasks.  This  is  a  bitwise  OR  of  one  or  more  of  the  fol 
lowing  symbols:  ShiftMask,  LockMask,  ControlMask,  ModlMask, 
Mod2Mask,  ModSMask,  Mod4Mask,  ModSMask,  or  AnyModifier. 
AnyModif  ier  is  equivalent  to  issuing  the  ungrab  key  request  for  all  pos 
sible  modifier  combinations  (including  no  modifiers). 

w  Specifies  the  ID  of  the  window  for  which  you  want  to  ungrab  the  specified 

keys. 

Description 

XUngrabKey  cancels  the  passive  grab  on  the  key  combination  on  the  specified  window  if  it 
was  grabbed  by  this  client.  A  modifiers  of  AnyModifier  is  equivalent  to  issuing  the 
request  for  all  possible  modifier  combinations  (including  the  combination  of  no  modifiers).  A 
keycode  of  AnyKey  is  equivalent  to  issuing  the  request  for  all  possible  nonmodifier  key 
codes.  This  call  has  no  effect  on  an  active  grab. 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 

Errors 

BadWindow 

BadValue  Invalid  keycode  or  modifiers  mask. 

Related  Commands 

XChangeActivePointerGrab,  XGrabButton,  XGrabKey,  XGrabKeyboard, 
XGrabPointer, XGrabServer, XUngrabButton,  XUngrabKeyboard, XUngrab- 
Pointer, XUngrabServer. 
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-x,,b-Grabb,ng /  XUngrabKeyboard 

Name 

XUngrabKeyboard  —  release  the  keyboard  from  an  active  grab. 

Synopsis 

XUngrabKeyboard (display,  time) 
Display  * display; 
Time  time; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

time  Specifies  the  time.  Pass  either  a  timestamp,  expressed  in  milliseconds,  or  the 

constant  CurrentTime.  If  this  time  is  earlier  than  the  last-keyboard-grab 
time  or  later  than  the  current  server  time,  the  keyboard  will  not  be  ungrabbed. 

Description 

XUngrabKeyboard  releases  any  active  grab  on  the  keyboard  by  this  client.  It  executes  as 
follows: 

Releases  the  keyboard  and  any  queued  events  if  this  client  has  it  actively  grabbed  from 
either  XGrabKeyboard  or  XGrabKey. 

Does  not  release  the  keyboard  and  any  queued  events  if  time  is  earlier  than  the  last-key 
board-grab  time  or  is  later  than  the  current  X  server  time. 

Generates  Focus  In  and  FocusOut  events. 

The  X  server  automatically  performs  an  UngrabKeyboard  if  the  grab_window  (argument 
to  XGrabkey  and  XGrabkeyboard)  that  becomes  unviewable. 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
Related  Commands 

XChangeActivePointerGrab,  XGrabButton,  XGrabKey,  XGrabKeyboard, 
XGrabPointer, XGrabServer, XUngrabButton, XUngrabKey, XUngrabPointer, 
XUngrabServer. 
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XUngrabPointer  V. 


-Xlib- Pointer- 


Name 

XUngrabPointer  —  release  the  pointer  from  an  active  grab. 

Synopsis 

XUngrabPointer (display,  time) 
Display  *display; 
Time  time; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

time  Specifies  the  time  when  the  grab  should  take  place.  Pass  either  a  timestamp, 

expressed  in  milliseconds,  or  the  constant  CurrentTime.  If  this  time  is 
earlier  than  the  last-pointer-grab  time  or  later  than  current  server  time,  the 
pointer  will  not  be  grabbed. 

Description 

XUngrabPointer  releases  an  active  grab  on  the  pointer  by  the  calling  client.  It  executes  as 
follows: 

•         Releases  the  pointer  and  any  queued  events,  if  this  client  has  actively  grabbed  the  pointer 
from  XGrabPo inter,  XGrabButton,  or  from  a  normal  button  press. 

Does  not  release  the  pointer  if  the  specified  time  is  earlier  than  the  last-pointer-grab  time 
or  is  later  than  the  current  X  server  time. 

Generates  EnterNotif y  and  LeaveNotif  y  events. 

The  X  server  performs  an  XUngrabPointer  automatically  if  the  event_window  or 
conf±ne_to  window  (arguments  of  XGrabButton  and  XGrabPointer)  becomes  not 
viewable,  or  if  the  conf  ine_to  window  is  moved,  completely  outside  the  root  window. 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
Related  Commands 

XChangeActivePointerGrab, XChangePointerControl,  XGetPointer- 
Control, XGetPointerMapping, XGrabPointer,  XQueryPointer, XSet- 
PointerMapping, XWarpPointer. 
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XUngrabServer 


Name 

XUngrabServer  —  release  the  server  from  grab. 

Synopsis 

XUngrabServer  (display) 
Display   *  display; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi  splay. 

Description 

XUngrabServer  releases  the  grabbed  server,  and  begins  execution  of  all  the  requests  queued 
during  the  grab.  XUngrabServer  is  called  automatically  when  a  client  closes  its  connection. 

For  more  information,  see  Volume  One,  Chapter  9,  The  Keyboard  and  Pointer. 
Related  Commands 

XChangeActivePointerGrab,  XGrabButton,  XGrabKey,  XGrabKeyboard, 
XGrabPointer,  XGrabServer,  XUngrabButton,  XUngrabKey,  XUngrab- 
Keyboard,  XUngrabPointer. 
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XUninstaliColormap  \ 


•Xlib- Colormaps— 


Name 

XUninstaliColormap  —  uninstall  a  colormap;  install  default  if  not  already  installed. 

Synopsis 

XUninstaliColormap  (display,  c/nap) 
Display  *  display; 
Colo rmap  c/nap ; 

Arguments 

di  spl ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi  spl ay . 

c/nap  Specifies  the  colormap  to  be  uninstalled. 

Description 

If  c/nap  is  an  installed  map  for  its  screen,  it  is  uninstalled.  If  the  screen's  default  colormap  is 
not  installed,  it  is  installed. 

If  c/nap  is  an  installed  map,  a  ColormapNotify  event  is  generated  on  every  window  having 
this  colormap  as  an  attribute.  If  a  colormap  is  installed  as  a  result  of  the  uninstall,  a 
ColormapNotify  event  is  generated  on  every  window  having  that  colormap  as  an  attribute. 

At  any  time,  there  is  a  subset  of  the  installed  colormaps,  viewed  as  an  ordered  list,  called  the 
required  list.  The  length  of  the  required  list  is  at  most  the  min_maps  specified  for  each  screen 
in  the  Display  structure.  When  a  colormap  is  installed  with  XInstallColormap  it  is 
added  to  the  head  of  the  required  list  and  the  last  colormap  in  the  list  is  removed  if  necessary  to 
keep  the  length  of  the  list  at  min_maps.  When  a  colormap  is  uninstalled  with  XUninstali 
Colormap  and  it  is  in  the  required  list,  it  is  removed  from  the  list.  No  other  actions  by  the 
server  or  the  client  change  the  required  list.  It  is  important  to  realize  that  on  all  but  high-per 
formance  workstations,  min_maps  is  likely  to  be  one. 

For  more  information  on  installing  and  uninstalling  colormaps,  see  Volume  One,  Chapter  7, 
Color. 

Errors 

BadColormap 

Related  Commands 

Def  aultColormap,  DisplayCells,  XCopyColormapAndFree,  XCreate- 
Colormap,  XFreeColormap,  XGetStandardColormap,  XInstallColormap, 
XListlnstalledColormaps.XSetStandardColormap,  XSetWindowColormap. 
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XUnionRectWithRegion 


Name 

XUnionRectWithRegion  —  add  a  rectangle  to  a  region. 

Synopsis 

XUnionRectWithRegion  (rectangle,  src_region,  dest_region) 
XRectangle  *  rectangle; 
Region  src_regi  on  ; 
Region  dest_region; 

Arguments 

rect  angl  e       Specifies  the  rectangle  to  add  to  the  region. 

src_regi  on     Specifies  the  source  region  to  be  used. 

dest_region  Specifies  the  resulting  region.  May  be  the  same  as  src_region. 

Description 

XUnionRectWithRegion  computes  the  destination  region  from  a  union  of  the  specified 
rectangle  and  the  specified  source  region.  The  source  and  destination  regions  may  be  the  same. 

One  common  application  of  this  function  is  to  simplify  the  combining  of  the  rectangles  speci 
fied  in  contiguous  Expose  events  into  a  clip_mask  in  the  GC,  thus  restricting  the  redrawn 
areas  to  the  exposed  rectangles.  Use  XUnionRectWithRegion  to  combine  the  rectangle  in 
each  Expose  event  into  a  region,  then  call  XSetRegion.  XSetRegion  sets  the 
clip_mask  in  a  GC  to  the  region.  In  this  case,  src_region  and  dest_region  would  be 
the  same  region. 

If  src_region  and  dest_region  are  not  the  same  region,  src_region  is  copied  to 
dest_region  before  the  rectangle  is  added  to  dest_region. 

For  more  information  on  regions,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
Structures 

typedef  struct  { 

short  x,  y; 

unsigned  short  width,  height; 
}  XRectangle; 

Region  is  a  pointer  to  an  opaque  data  type. 
Related  Commands 

XClipBox,  XDestroyRegion,  XEmpty  Region,  XEqualRegion,  Xlntersect- 
Region,  XOf  f  setRegion,  XPointlnRegion,  XPolygonRegion,  XRectlnRegion, 
XSetRegion,  XShrinkRegion,  XSubtractRegion,  XUnionRegion,  XXorRegion. 
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XUnionRegion  \ 


•Xlib-  Regions- 


Name 

XUnionRegion  —  compute  the  union  of  two  regions. 

Synopsis 

XUnionRegion  (sra,  srb,  dr) 
Region  sra,  srb; 
Region  dr; 

Arguments 

sra  Specify  the  two  regions  in  which  you  want  to  perform  the  computation, 

srb 

dr  Returns  the  result  of  the  computation. 

Description 

XUnionRegion  computes  the  union  of  two  regions  and  places  the  result  in  dr.  The  resulting 
region  will  contain  all  the  area  of  both  the  source  regions. 

For  more  information  on  regions,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion,  XDestroyRegion,  XEmptyRegion,  XEqualRegion, 
XIntersectRegion,  XOf  f  setRegion,  XPointlnRegion,  XPolygonRegion, 
XRectlnRegion,  XSetRegion,  XShrinkRegion,  XSubtractRegion,  XUnion- 
RectWithRegion, XXorRegion. 
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XUniqueContext 

— Xlib  -  Context  Manager ' 

Name 

XUniqueContext  —  create  a  new  context  ID  (not  graphics  context). 

Synopsis 

XContext  XUniqueContext ( ) 

Description 

The  context  manager  allows  association  of  arbitrary  data  with  a  resource  ID.  This  call  creates  a 
unique  ID  that  can  be  used  in  subsequent  calls  to  XFindContext,  XDeleteContext,  and 
XSaveContext. 

For  more  information  on  the  context  manager,  see  Volume  One,  Chapter  13,  Other  Program 
ming  Techniques. 

Structures 

typedef  int  XContext; 


Related  Commands 

XDeleteContext, XFindContext,  XSaveContext. 
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XUnloadFont  \ Xlib .  Fonts_ 

Name 

XUnloadFont  —  unload  a  font 

Synopsis 

XUnloadFont  (  display,  font ) 
Display  * display; 
Font  font; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

fon  t  Specifies  the  ID  of  the  font  to  be  unloaded. 

Description 

XUnloadFont  indicates  to  the  server  that  this  client  no  longer  needs  the  specified  font  The 
font  may  be  unloaded  on  the  X  server  if  this  is  the  last  client  that  needs  the  font  In  any  case, 
the  font  should  never  again  be  referenced  by  this  client  because  Xlib  destroys  the  resource  ID. 

For  more  information  on  loading  and  unloading  fonts,  see  Volume  One,  Chapter  6,  Drawing 
Graphics  and  Text. 

Errors 

BadFont 

Related  Commands 

XCreateFontCursor, XFreeFont, XFreeFontlnf o,  XFreeFontNames, XFree- 
FontPath, XGetFontPath, XGetFontProperty, XListFonts, XListFontsWith- 
Inf o, XLoadFont, XLoadQueryFont, XQueryFont, XSetFont,  XSetFontPath. 
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J  XUnmapSubwindows 

— Xlib  -  Mapping ' 

Name 

XUnmapSubwindows  —  unmap  all  subwindows  of  a  given  window. 

Synopsis 

XUnmapSubwindows (display,  w) 
Display  * display ; 
Window  w; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  whose  subwindows  are  to  be  unmapped. 

Description 

XUnmapSubwindows  performs  an  XUnmapWindow  on  all  mapped  children  of  w,  in  bottom 
to  top  stacking  order.  (It  does  not  unmap  subwindows  of  subwindows.) 

XUnmapSubwindows  also  generates  an  UnmapNotify  event  on  each  subwindow  and  gen 
erates  exposure  events  on  formerly  obscured  windows.  This  is  much  more  efficient  than 
unmapping  many  subwindows  one  at  a  time,  since  much  of  the  work  need  only  be  performed 
once  for  all  of  the  subwindows  rather  than  for  each  subwindow. 

For  more  information  on  window  mapping,  see  Volume  One,  Chapter  2,  X  Concepts. 
Errors 

BadWindow 

Related  Commands 

XMapRaised,  XMapSubwindows,  XMapWindow,  XUnmapWindow. 
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XUnmapWindow  \ 


•Xlib- Mapping- 


Name 

XUnmapWindow  —  unmap  a  window. 

Synopsis 

XUnmapWindow  ( di spl ay,  w ) 
Display  *  display; 
Window  w; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  window  ID. 

Description 

XUnmapWindow  removes  w  and  all  its  descendants  from  the  screen  (but  does  not  unmap  the 
descendents).  If  w  is  already  unmapped,  XUnmapWindow  has  no  effect.  Otherwise,  w  is 
unmapped  and  an  UnmapNotify  event  is  generated.  Normal  exposure  processing  on  for 
merly  obscured  windows  is  performed. 

Descendants  of  w  will  not  be  visible  until  w  is  mapped  again.  In  other  words,  the  subwindows 
are  still  mapped,  but  are  not  visible  because  w  is  unmapped.  Unmapping  a  window  will  gener 
ate  exposure  events  on  windows  that  were  formerly  obscured  by  w. 

For  more  information  on  window  mapping,  see  Volume  One,  Chapter  2,  X  Concepts. 

Errors 

BadWindow 

Related  Commands 

XMapRaised,  XMapSubwindows,  XMapWindow,  XUnmapSubwindows. 
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XVisuallDFromVisual 

— Xlib  -  Window  Manager  Hints- 
Name 

XVisuallDFromVisual  —  obtain  the  visual  ID  from  a  visual. 

Synopsis 

VisuallD  XVisuallDFromVisual (visual) 
Visual  * visual; 

Arguments 

visual  Specifies  the  visual  type. 

Description 

XVisuallDFromVisual  returns  the  visual  ID  for  the  specified  visual.  This  is  needed  when 
filling  an  xvisuallnf  o  structure  template  before  calling  XGetvisuallnf  o. 
For  more  information,  see  Volume  One,  Chapter  10,  Interclient  Communication. 

Related  Commands 

XGetvisuallnf o. 
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XWMGeometry  V Xllb_  window  Manager  „,„„_ 

Name 

XWMGeometry  —  obtain  a  window's  geometry  information. 

Synopsis 

int   XWMGeometry (display,    screen,    user_geomr    def_geomr    bwidth, 

hints,    x,    y,    width,    height,    gravity) 
Display    *display; 
int    screen; 
char    *user_geom; 
char   *def_geom; 
unsigned  int  bwidth; 
XSizeHints    *hints; 
int    *x,     *y;  /*   RETURN    */ 

int    *  width,    *height ;         /*   RETURN    */ 
int    *  gravity;  /*   RETURN    */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

screen  Specifies  the  screen. 

user_geom  Specifies  the  user-specified  geometry  or  NULL. 

def_geom  Specifies  the  application's  default  geometry  or  NULL. 

bwi  dth  Specifies  the  border  width. 

hints  Specifies  the  size  hints  for  the  window  in  its  normal  state. 

x 

y  Return  the  x  and  y  offsets. 

width 

height  Return  the  width  and  height  determined. 

gra vi  ty  Returns  the  window  gravity. 

Availability 

Release  4  and  later. 

Description 

XWMGeometry  combines  possibly  incomplete  or  nonexistent  geometry  information  (given  in 
the  format  used  by  XParseGeometry)  specified  by  the  user  and  by  the  calling  program  with 
complete  program-supplied  default  size  hints  (usually  the  ones  to  be  stored  in 
WM_NORMAL_HINTS)  and  returns  the  position,  size,  and  gravity  (NorthWestGravity, 
NorthEastGravity,  SouthEastGravity  or  SouthWestGravity)  that  describe  the 
window.  If  the  base  size  is  not  set  in  the  XSizeHints  structure,  the  minimum  size  is  used  if 
set  Otherwise,  a  base  size  of  zero  is  assumed.  If  no  minimum  size  is  set  in  the  hints  structure, 
the  base  size  is  used.  A  mask  (in  the  form  returned  by  XParseGeometry)  that  describes 
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Xlib  -  Window  Manager  Hints  (continued)  X  WMGeo m et ry 

which  values  came  from  the  user  and  whether  or  not  the  position  coordinates  are  relative  to  the 
right  and  bottom  edges  is  returned  (which  will  have  already  been  accounted  for  in  the  x  and  y 
values). 

Note  that  invalid  user  geometry  specifications  can  cause  a  width  or  height  of  zero  to  be 
returned.  The  caller  may  pass  the  address  of  the  win_gravity  field  of  the  hints  argument 
as  the  gravity  argument 

For  more  information,  see  Volume  One,  Chapter  10, Inter -client  Communication. 
Structures 

typedef   struct    { 

long   flags;  /*   marks   which   fields    in   this    structure   are 

/*   defined   */ 

int  x,  y;        /*  obsolete  for  new  window  mgrs,  but  clients  */ 
int  width,  height;   /*  should  set  so  old  wm' s  don't  mess  up  */ 
int  min_width,  min_height; 
int  max_width,  max_height; 
int  width_inc,  height_inc; 
struct  { 

int  x;   /*  numerator  */ 

int  y;   /*  denominator  */ 
}  min_aspect,  max_aspect; 

int  base_width,  base_height;     /*  added  by  ICCCM  version  1  */ 
int  win_gravity;  /*  added  by  ICCCM  version  1  */ 

}  XSizeHints 

Related  Commands 

XChangeWindowAttributes, XParseGeometry,  XSetWMProperties. 
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XWarpPointer  V Xllb_  Polnler_ 

Name 

XWarpPointer  —  move  the  pointer  to  another  point  on  the  screen. 

Synopsis 

XWarpPointer (display,  src_w,  dest_w,  src_x,  src_y , 

src_widthr  src_height ,  dest_x,  dest_y) 
Display  *display; 
Window  src_w,  dest_w; 
int  src_x,  src_y; 

unsigned  int  src_width,  src_height ; 
int  dest_x,  dest_y; 

Arguments 

di splay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

src_w  Specifies  the  ID  of  the  source  window.  You  can  also  pass  None. 

dest_w  Specifies  the  ID  of  the  destination  window.  You  can  also  pass  None. 

src_x  Specify  the  x  and  y  coordinates  within  the  source  window.  These  are  used 

src_y  with    src_width  and   src_height  to  determine   the  rectangle   the 

pointer  must  be  in  order  to  be  moved.  They  are  not  the  present  pointer  posi 
tion.  If  src_y  is  None,  these  coordinates  are  relative  to  the  root  window 
of  src_w. 

src_width  Specify  the  width  and  height  in  pixels  of  the  source  area.  Used  with  src_x 
src_height  and  src_y. 

dest_x  Specify  the  destination  x  and  y  coordinates  within  the  destination  window. 

dest_y  If  dest_w  is  None,  these  coordinates  are  relative  to  the  root  window  of 

dest_w. 

Description 

XWarpPointer  moves  the  pointer  suddenly  from  one  point  on  the  screen  to  another. 

If  dest_w  is  a  window,  XWarpPointer  moves  the  pointer  to  [dest_x,  dest_y]  relative  to 
the  destination  window's  origin.  If  dest_w  is  None,  XWarpPointer  moves  the  pointer 
according  to  the  offsets  [dest_x,  dest_y]  relative  to  the  current  position  of  the  pointer. 

If  src_window  is  None,  the  move  is  independent  of  the  current  cursor  position  (dest_x  and 
dest_y  use  global  coordinates).  If  the  source  window  is  not  None,  the  move  only  takes  place 
if  the  pointer  is  currently  contained  in  a  visible  portion  of  the  rectangle  of  the  source  window 
(including  its  inferiors)  specified  by  src_x,  src_y,  src_width  and  src_height.  If 
src_width  is  zero  (0),  the  pointer  must  be  between  src_x  and  the  right  edge  of  the  window 
to  be  moved.  If  src_height  is  zero  (0),  the  pointer  must  be  between  src_y  and  the  bottom 
edge  of  the  window  to  be  moved. 

XWarpPointer  cannot  be  used  to  move  the  pointer  outside  the  conf  ine_to  window  of  an 
active  pointer  grab.  If  this  is  attempted  the  pointer  will  be  moved  to  the  point  on  the  border  of 
the  conf  ine_to  window  nearest  the  requested  destination. 
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Xlib-  Pointer  (continued)  XWarpPointer 

XWarpPointer  generates  events  as  if  the  user  had  (instantaneously)  moved  the  pointer. 

This  function  should  not  be  used  unless  absolutely  necessary,  and  then  only  in  tightly  con 
trolled,  predictable  situations.  It  has  the  potential  to  confuse  the  user. 

Errors 

BadWindow 

Related  Commands 

XChangeActivePointerGrab, XChangePointerControl, XGetPointer- 
Control, XGetPointerMapping, XGrabPointer, XQueryPointer, XSet- 
PointerMapping, XUngrabPointer. 
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XWindowEvent  A XIib  _  lnput  Hand.ing- 

Name 

XWindowEvent  —  remove  the  next  event  that  matches  the  specified  mask  and  window. 

Synopsis 

XWindowEvent  (display,  w,  event_mask,  rep) 
Display  *  display; 
Window  w; 
long  event_mask; 
XEvent  *rep;  /*  RETURN  */ 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

w  Specifies  the  ID  of  the  window  whose  next  matching  event  you  want. 

event_mask     Specifies  the  event  mask.  See  XSelectlnput  for  a  complete  list  of  event 
masks. 

rep  Returns  the  event  removed  from  the  input  queue. 

Description 

XWindowEvent  removes  the  next  event  in  the  queue  which  matches  both  the  passed  window 
and  the  passed  mask.  The  event  is  copied  into  an  XEvent  structure  supplied  by  the  caller. 
Other  events  in  the  queue  are  not  discarded.  If  no  such  event  has  been  queued,  XWindow 
Event  flushes  the  request  buffer  and  waits  until  one  is  received. 

Structures 

See  individual  event  structures  described  in  Volume  One,  Chapter  8,  Events,  and  Appendix  F, 
Structure  Reference  in  this  volume. 

Related  Commands 

QLength, XAllowEvents, XChecklf Event,  XCheckMaskEvent, XCheckTyped- 
Event, XCheckTypedWindowEvent,  XCheckWindowEvent, XEvent sQueued, 
XGetInputFocus,XGetMotionEvents,XIf Event,  XMaskEvent,  XNextEvent, 
XPeekEvent, XPeeklf Event, XPending,  XPutBackEvent,  XSelectlnput, 
XSendEvent,  XSetlnputFocus,  XSynchronize. 
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J  XWithdrawWindow 

— Xlib  -  Window  Manager  Hints * 

Name 

XWithdrawWindow  —  request  that  a  top-level  window  be  withdrawn. 

Synopsis 

Status  XWithdrawWindow  (display,  w,  screen_n umber) 
Display  * display; 
Window  w; 
int  screen_n umber; 

Arguments 

di spl ay  Specifies  a  connection  to  an  X  server;  returned  from  xopenDi  spl ay . 

w  Specifies  the  window. 

s creen_n umber 

Specifies  the  appropriate  screen  number  on  the  server. 

Availability 

Release  4  and  later. 

Description 

XWithdrawWindow  informs  the  window  manager  that  the  specified  window  and  its  icon 
should  be  unmapped.  It  unmaps  the  specified  window  and  sends  a  synthetic  UnmapNotify 
event  to  the  root  window  of  the  specified  screen.  Window  managers  may  elect  to  receive  this 
message  and  may  treat  it  as  a  request  to  change  the  window's  state  to  withdrawn.  When  a  win 
dow  is  in  the  withdrawn  state,  neither  its  normal  nor  its  iconic  representation  is  visible. 
XWithdrawWindow  returns  a  nonzero  status  if  the  UnmapNotify  event  is  successfully  sent; 
otherwise,  it  returns  a  zero  status. 

For  more  information,  see  Volume  One,  Chapter  10,  Inter  client  Communication. 

Errors 

BadWindow 

Related  Commands 

XlconifyWindow,  XReconf igureWindow. 
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XWriteBitmapFile  V Xlib  _  Pixmaps  and  Tlles_ 

Name 

XWriteBitmapFile  —  write  a  bitmap  to  a  file. 

Synopsis 

int  XWriteBitmapFile (display,  filename,  bitmap,  width, 

height,  x_hot,  y_hot) 
Display  * display ; 
char  * filename; 
Pixmap  bitmap; 
unsigned  int  width,  height; 
int  x_hotr  y_hot ; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

filename         Specifies  the  filename  to  use.  The  format  of  the  filename  is  operating  system 
specific. 

bi  tmap  Specifies  the  bitmap  to  be  written. 

wi  dth  Specify  the  width  and  height  in  pixels  of  the  bitmap  to  be  written. 

height 

x_hot  Specify  where  to  place  the  hotspot  coordinates  (or  -1,-1  if  none  present)  in 

y_hot  the  file. 

Description 

XWriteBitmapFile  writes  a  bitmap  to  a  file.  The  file  is  written  out  in  X  version  11  bitmap 
file  format,  shown  below. 

If  the  file  cannot  be  opened  for  writing,  XWriteBitmapFile  returns  BitmapOpen- 
Failed.  If  insufficient  memory  is  allocated  XWriteBitmapFile  returns  Bitmap- 
NoMemory.  Otherwise,  on  no  error,  XWriteBitmapFile  returns  BitmapSuccess. 

If  x_hot  and  y_hot  are  not  -1,  -1,  then  XWriteBitmapFile  writes  them  out  as  the 
hotspot  coordinates  for  the  bitmap. 

The  following  is  an  example  of  the  contents  of  a  bitmap  file  created.  The  name  used  ("gray"  in 
this  example)  is  the  portion  of  filename  after  the  last "/". 

#define  gray_width  16 

tdefine  gray_height  16 

#define  gray_x_hot  8 

#define  gray_y_hot  8 

static  char  gray_bits[]  =  { 

Oxf8,  Oxlf,  Oxe3,  Oxc7,  Oxcf,  Oxf3,  Ox9f,  Oxf9,  Oxbf,  Oxfd,  0x33,  Oxcc, 
Ox7f,  Oxfe,  Ox7f,  Oxfe,  Ox7e,  Ox7e,  Ox7f,  Oxfe,  0x37,  Oxec,  Oxbb,  Oxdd, 
Ox9c,  0x39,  Oxcf,  Oxf3,  Oxe3,  Oxc7,  Oxf8,  Oxlf}; 

For  more  information  on  bitmaps,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 
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Xlib  -  Pixmaps  and  Tiles  (continued)  X WriteBitmapFile 

Errors 

BadAlloc 

BadDrawable 

BadMatch          The  specified  width  and  height  did  not  match  dimensions  of  the  specified 
jbi  tmap. 

Related  Commands 

XCreateBitmapFromData.XCreatePixmap,  XCreatePixmapFromBitmapData, 
XFreePixmap,XQueryBestSize,XQueryBestStipple,XQueryBestTile, 
XReadBitmapFile,  XSetTile,  XSetWindowBackgroundPixmap,  XSetWindow- 
BorderPixmap. 
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•Xlib- Regions- 


Name 

XXorRegion  —  calculate  the  difference  between  the  union  and  intersection  of  two  regions. 

Synopsis 

XXorRegion  ( sra,    srb,    dr) 
Region   sra,    srb; 
Region   dr;  /*  RETURN    */ 

Arguments 

sra  Specify  the  two  regions  on  which  you  want  to  perform  the  computation, 

srb 

dr  Returns  the  result  of  the  computation. 

Description 

XXorRegion  calculates  the  union  minus  the  intersection  of  two  regions,  and  places  it  in  dr. 
Xor  is  short  for  "Exclusive  OR",  meaning  that  a  pixel  is  included  in  dr  if  it  is  set  in  either  sra 
or  srb  but  not  in  both. 

For  more  information  on  regions,  see  Volume  One,  Chapter  6,  Drawing  Graphics  and  Text. 

Structures 

Region  is  a  pointer  to  an  opaque  structure  type. 

Related  Commands 

XClipBox,  XCreateRegion,  XDestroyRegion,  XEmptyRegion,  XEqualRegion, 
XIntersectRegion, XOf f setRegion,  XPointlnRegion,  XPolygonRegion, 
XRectlnRegion, XSetRegion,  XShrinkRegion,  XSubtractRegion, XUnion- 
RectWithRegion, XUnionRegion. 
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Function  Group  Summary 


This  quick  reference  is  intended  to  help  you  find  and  use  the  right  function  for  a  particular 
task.  It  supplies  two  lists: 

•  Listing  of  Functions  by  Groups 

•  Alphabetical  Listing  of  Functions 

Both  functions  and  macros  are  listed  in  all  the  groups  in  which  they  belong.  Therefore,  sev 
eral  of  them  are  listed  more  than  once. 

Remember  that  Xlib  functions  begin  with  the  letter  "X";  macros  do  not 


A.1   Group  Listing  with  Brief  Descriptions 


Association  Tables 


XCreateAssocTable 

XDeleteAssoc 

XDestroyAssocTable 

XLookUpAssoc 

XMakeAssoc 


Create  a  new  association  table  (X10). 

Delete  an  entry  from  an  association  table. 

Free  the  memory  allocated  for  an  association  table. 

Obtain  data  from  an  association  table. 

Create  an  entry  in  an  association  table. 


Buffers 


XStoreBuffer 

XStoreBytes 

XFetchBuffer 

XFetchBytes 

XRotateBuffers 


Store  data  in  a  cut  buffer. 
Store  data  in  cut  buffer  0. 
Return  data  from  a  cut  buffer. 
Return  data  from  cut  buffer  0. 
Rotate  the  cut  buffers. 
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Client  Connections 


XKillClient 
XSetCloseDownMode 


Destroy  a  client  or  its  remaining  resources. 
Change  the  close  down  mode  of  a  client. 


Colorcells 


XAllocColor 

XAllocColorCells 
XAllocColorPlanes 
XAllocNamedColor 
XLookupColor 

XParseColor 

XQueryColor 

XQueryColors 

XStoreColor 

XStoreColors 

XStoreNamedColor 
XFreeColors 
BlackPixel 
WhitePixel 


Allocate  a  read-only  colormap  cell  with  closest  hardware-sup 
ported  color. 

Allocate  read/write  (nonshared)  colorcells. 
Allocate  read/write  (nonshareable)  color  planes. 
Allocate  a  read-only  colorcell  from  color  name. 
Get  database  RGB  values  and  closest  hardware-supported 
RGB  values  from  color  name. 

Look  up  or  translate  RGB  values  from  color  name  or  hexade 
cimal  value. 

Obtain  the  RGB  values  for  a  specified  pixel  value. 
Obtain  RGB  values  and  flags  for  each  specified  pixel  value. 
Set  or  change  a  read/write  entry  of  a  colormap  to  the  closest 
available  hardware  color. 

Set  or  change  read/write  colorcells  to  the  closest  available 
hardware  colors. 

Allocate  a  read/write  colorcell  by  English  color  name. 
Free  colormap  cells  or  planes. 

Return  a  black  pixel  value  on  the  default  colormap  of  screen. 
Return  a  pixel  value  representing  white  in  default  colormap. 


Colormaps 


XCopyColormapAndFree 

XCreateColormap 

XFreeColormap 

XGetStandardColormap 

XSetStandardColormap 

XSetWindowColormap 

XInstallColormap 

XUninstallColormap 

XListlnstalledColormaps 

Default Colormap 

DefaultColormapOf Screen 

DisplayCells 


Copy  a  colormap  and  return  a  new  colormap  ID. 
Create  a  colormap. 

Delete  a  colormap  and  install  the  default  colormap. 
Get  the  standard  colormap  property. 
Change  the  standard  colormap  property. 
Set  the  colormap  for  a  specified  window. 
Install  a  colormap. 

Uninstall  a  colormap;  install  default  if  not  already  installed. 
Get  a  list  of  installed  colormaps. 
Return  the  default  colormap  on  the  default  screen. 
Return  the  default  colormap  on  the  specified  screen. 
Return  the  maximum  number  of  colormap  cells  on  the  con 
nected  display. 


Context  Manager 


XDeleteContext 
XFindContext 


Delete  a  context  entry  for  a  given  window  and  type. 
Get  data  from  the  context  manager  (not  graphics  context). 
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Context  Manager  (continued) 


XSaveContext 
XUniqueContext 


Save  a  data  value  corresponding  to  a  window  and  context  type 

(not  graphics  context). 

Create  a  new  context  ID  (not  graphics  context). 


Cursors 


XDefineCursor 

XUndefineCursor 

XCreateFontCursor 

XCreateGlyphCursor 

XCreatePixmapCursor 

XFreeCursor 

XRecolorCursor 

XQueryBest Cursor 

XQueryBestSize 


Assign  a  cursor  to  a  window. 

Disassociate  a  cursor  from  a  window. 

Create  a  cursor  from  the  standard  cursor  font 

Create  a  cursor  from  font  glyphs. 

Create  a  cursor  from  two  bitmaps. 

Destroy  a  cursor. 

Change  the  color  of  a  cursor. 

Get  the  closest  supported  cursor  sizes. 

Obtain  the  "best"  supported  cursor,  tile,  or  stipple  size. 


Display  Specifications 


DefaultColormap 

DefaultDepth 

DefaultGC 

Default Screen 


DefaultVisual 
DisplayCells 

DisplayHeight 

DisplayHeightMM 

DisplayPlanes 

DisplayString 

DisplayWidth 

DisplayWidthMM 

RootWindow 

ScreenCount 

XDisplayMotionBufferSize 

XListDepths 

XListPixmapFormats 

XMaxRequestSize 

XResourceManager String 


Return  the  default  colormap  on  the  specified  screen. 
Return  the  depth  of  the  default  root  window  for  a  screen. 
Return  the  default  graphics  context  for  the  root  window  of  a 
screen. 

Return  the  screen  integer;  the  last  segment  of  a  string  passed  to 
XOpenDisplay,  or  the  DISPLAY  environment  variable  if 
NULL  was  used. 

Return  the  default  visual  structure  for  a  screen. 
Return  the  maximum  number  of  colormap  cells  on  the  con 
nected  display. 

Return  an  integer  that  describes  the  height  of  the  screen  in  pix 
els. 

Return  the  height  of  the  specified  screen  in  millimeters. 
Return  the  number  of  planes  on  the  connected  display. 
Return  the  string  that  was  passed  to  XOpenDisplay  or  if 
that  was  NULL,  the  DISPLAY  variable. 
Return  the  width  of  the  screen  in  pixels. 
Return  the  width  of  the  specified  screen  in  millimeters. 
Return  the  ID  of  the  root  window. 
Return  the  number  of  available  screens. 
Return  size  of  server's  motion  history  buffer. 
Return  a  list  of  the  depths  supported  on  this  server. 
Return  a  list  of  the  pixmap  formats  supported  on  this  server. 
Return  maximum  request  size  allowed  on  this  server. 
Return  string  containing  user's  resource  database. 
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Drawing  Primitives 


XDraw 

XDrawArc 

XDrawArcs 

XDrawFilled 

XDrawLine 

XDrawLines 

XDrawPoint 

XDrawPoints 

XDrawRect angle 

XDrawRect angles 

XDrawSegments 

XCopyArea 

XCopyPlane 

XFillArc 

XFillArcs 

XFillPolygon 

XFillRectangle 

XFillRect angles 

XClearArea 

XClearWindow 


Draw  a  polyline  or  curve  between  vertex  list  (from  X10). 

Draw  an  arc  fitting  inside  a  rectangle. 

Draw  multiple  arcs. 

Draw  a  filled  polygon  or  curve  from  vertex  list  (from  X10). 

Draw  a  line  between  two  points. 

Draw  multiple  connected  lines. 

Draw  a  point. 

Draw  multiple  points. 

Draw  an  outline  of  a  rectangle. 

Draw  the  outlines  of  multiple  rectangles. 

Draw  multiple  disjoint  lines. 

Copy  an  area  of  a  drawable. 

Copy  a  single  plane  of  a  drawable  into  a  drawable  with  depth, 

applying  pixel  values. 

Fill  an  arc. 

Fill  multiple  arcs. 

Fill  a  polygon. 

Fill  a  rectangular  area. 

Fill  multiple  rectangular  areas. 

Clear  a  rectangular  area  in  a  window. 

Clear  an  entire  window. 


Errors 


XGetErrorDatabaseText 

XGetErrorText 

XSetErrorHandler 

XSetlOErrorHandler 

XDisplayName 

XSetAfterFunction 

XSynchronize 


Obtain  error  messages  from  the  error  database. 

Obtain  a  description  of  error  code. 

Set  a  nonfatal  error  event  handler. 

Handle  fatal  I/O  errors. 

Report  the  display  name  when  connection  to  a  display  fails. 

Set  a  function  called  after  all  Xlib  functions. 

Enable  or  disable  synchronization  for  debugging. 


Events 


XSelectlnput 

XSendEvent 

XSetlnputFocus 

XGetlnputFocus 

XWindowEvent 

XCheckWindowEvent 

XCheckTypedEvent 

XCheckTypedWindowEvent 

XMaskEvent 

XCheckMaskEvent 


Select  the  event  types  to  be  sent  to  a  window. 
Send  an  event 

Set  the  keyboard  focus  window. 
Return  the  current  keyboard  focus  window. 
Remove  the  next  event  matching  mask  and  window. 
Remove  the  next  event  matching  both  passed  window  and  pas 
sed  mask;  don't  wait. 

Return  the  next  event  in  queue  that  matches  event  type;  don't 
wait. 

Return  the  next  event  in  queue  matching  type  and  window. 
Remove  the  next  event  that  matches  mask. 
Remove  the  next  event  that  matches  mask;  don't  wait. 


550 


Xlib  Reference  Manual 


Events  (continued) 


XI f Event 

XChecklfEvent 

XPeekEvent 

XPeeklfEvent 

XAllowEvents 

XGetMotionEvents 

XNextEvent 

XPutBackEvent 

XEventsQueued 

XPending 

XSynchronize 
QLength 


Wait  for  matching  event 

Check  the  event  queue  for  a  matching  event 

Get  an  event  without  removing  it  from  the  queue. 

Get  an  event  without  recovering  it  from  the  queue;  don't  wait 

Control  the  behavior  of  keyboard  and  pointer  events  when 

these  resources  are  grabbed. 

Get  pointer  motion  events. 

Get  the  next  event  of  any  type  or  window. 

Push  an  event  back  on  the  input  queue. 

Check  the  number  of  events  in  the  event  queue. 

Rush  the  request  buffer  and  return  the  number  of  pending 

input  events. 

Enable  or  disable  synchronization  for  debugging. 

Return  the  current  length  of  the  input  queue  on  the  connected 

display. 


Extensions 


XFreeExtensionList 
XList Ext ens ions 
XQueryExtension 


Free  memory  allocated  for  a  list  of  installed  extensions  to  X. 
Return  a  list  of  all  extensions  to  X  supported  by  the  server. 
Get  extension  information. 


Fonts 


XLoadFont 

XUnloadFont 

XFreeFont 

XFreeFontlnfo 

XFreeFontNames 

XFreeFontPath 

XListFonts 

XListFontsWithlnfo 

XQueryFont 

XSetFont 

XSetFontPath 

XGetFontPath 

XGetFont Property 

XCreateFont Cursor 


Load  a  font  if  not  already  loaded;  get  font  ID. 

Unload  a  font 

Unload  a  font  and  free  storage  for  the  font  structure. 

Free  multiple  font  information  arrays. 

Free  the  font  name  array. 

Free  the  memory  allocated  by  XGetFontPath. 

Return  a  list  of  the  available  font  names. 

Obtain  the  names  and  information  about  loaded  fonts. 

Return  information  about  a  loaded  font. 

Set  the  current  font  in  a  graphics  context. 

Set  the  font  search  path. 

Get  the  current  font  search  path. 

Get  a  font  property  given  its  atom. 

Create  a  cursor  from  the  standard  cursor  font 


Grabbing 


XGrabKey 

XUngrabKey 

XGrabKeyboard 

XUngrabKeyboard 

XGrabButton 


Grab  a  key. 

Release  a  key  from  grab. 

Grab  the  keyboard. 

Release  the  keyboard  from  grab. 

Grab  a  pointer  button. 
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Grabbing  (continued) 


XUngrabButton 

XGrabPointer 

XUngrabPointer 

XGrabServer 

XUngrabServer 

XChangeActivePointerGrab 


Release  a  button  from  grab. 

Grab  the  pointer. 

Release  the  pointer  from  grab. 

Grab  the  server  grab. 

Release  the  server  from  grab. 

Change  the  parameters  of  an  active  pointer  grab. 


Graphics  Context 


XCreateGC 

XChangeGC 
XCopyGC 
XFreeGC 
XGContextFromGC 

XGetGCValues 

XSetArcMode 

XSetClipMask 

XSetClipOrigin 

XSetClipRectangles 

XSetRegion 

XSetDashes 

XSet Line Attributes 

XSetFillRule 

XSetFillStyle 

XSetTile 

XSetStipple 

XSetTSOrigin 

XSetGraphicsExposures 

XSetForeground 

XSet Background 

XSetFunction 

XSetPlaneMask 

XSetState 

XSetSubwindowMode 
DefaultGC 


Create  a  new  graphics  context  for  a  given  screen  with  the 

depth  of  the  specified  drawable. 

Change  the  components  of  a  given  graphics  context. 

Copy  a  graphics  context. 

Free  a  graphics  context. 

Obtain  the  GContext  (resource  ID)  associated  with  the 

specified  graphics  context. 

Get  GC  component  values  from  Xlib's  GC  cache. 

Set  the  arc  mode  in  a  graphics  context. 

Set  clip_mask  pixmap  in  a  graphics  context. 

Set  the  clip  origin  in  a  graphics  context. 

Set  clip_mask  in  a  graphics  context  to  the  list  of  rectangles. 

Set  clip_mask  of  the  graphics  context  to  the  specified 

region. 

Set  dash_of  f  set  and  dashes  (for  lines)  in  a  graphics 

context. 

Set  the  line  drawing  components  in  a  graphics  context. 

Set  the  fill  rule  in  a  graphics  context. 

Set  the  fill  style  in  a  graphics  context. 

Set  the  fill  tile  in  a  graphics  context. 

Set  the  stipple  in  a  graphics  context. 

Set  the  tile/stipple  origin  in  a  graphics  context. 

Set  graphics_exposures  in  a  graphics  context. 

Set  the  foreground  pixel  value  in  a  graphics  context. 

Set  the  background  pixel  value  in  a  graphics  context. 

Set  the  bitwise  logical  operation  in  a  graphics  context. 

Set  the  plane  mask  in  a  graphics  context. 

Set  the  foreground,  background,  logical  function  and  plane 

mask  in  a  graphics  context. 

Set  the  subwindow  mode  in  a  graphics  context. 

Return  the  default  graphics  context  for  the  root  window  of  a 

screen. 
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Host  Access 


XAddHost 

XAddHosts 

XListHosts 

XRemoveHost 

XRemoveHosts 

XDisableAccessControl 

XEnableAccessControl 

XSetAccessControl 


Add  a  host  to  the  access  control  list. 

Add  multiple  hosts  to  the  access  control  list. 

Obtain  a  list  of  hosts  having  access  to  this  display. 

Remove  a  host  from  the  access  control  list. 

Remove  multiple  hosts  from  the  access  control  list. 

Allow  access  from  any  host 

Use  access  control  list  to  allow  or  deny  connection  requests. 

Disable  or  enable  access  control. 


HouseKeeping 


XFree 

XOpenDisplay 
XCloseDisplay 
XNoOp 


Free  specified  in-memory  data  created  by  an  Xlib  function. 
Connect  a  client  program  to  an  X  server. 
Disconnect  a  client  program  from  an  X  server  and  display. 
Send  a  NoOp  to  exercise  connection  with  the  server. 


Images 


XCreate Image 
XDes troy Image 
XPutlmage 
XSublmage 
XGet Image 
XGetSublmage 

XAddPixel 
XPutPixel 
XGetPixel 
ImageByteOrder 


Allocate  memory  for  an  Xlmage  structure. 
Deallocate  memory  associated  with  an  image. 
Draw  a  rectangular  image  on  a  window  or  pixmap. 
Create  a  subimage  from  part  of  an  image. 
Place  contents  of  a  rectangle  from  drawable  into  an  image. 
Copy  a  rectangle  in  drawable  to  a  location  within  the  pre 
existing  image. 

Add  a  constant  value  to  every  pixel  value  in  an  image. 
Set  a  pixel  value  in  an  image. 
Obtain  a  single  pixel  value  from  an  image. 
Specify  the  required  byte  order  for  images  for  each  scan  line 
unit  in  XYFormat  (bitmap)  or  for  each  pixel  value  in  ZFor- 
mat.  Returns  either  LSBFirst  orMSBFirst. 


Interclient  Communication 


(see  Window  Manager  Hints,  Selections,  and  Cut  Buffers) 


Keyboard 


XKeycodeToKeysym 

XKeysymToKeycode 

XKeysymToString 

XStringToKeysym 

XLookupKeysym 

XRebindKeysym 


Convert  a  keycode  to  a  keysym. 

Convert  a  keysym  to  the  appropriate  keycode. 

Convert  a  keysym  symbol  to  a  string. 

Convert  a  keysym  name  string  to  a  keysym. 

Get  the  keysym  corresponding  to  a  keycode  in  a  structure. 

Rebind  a  keysym  to  a  string  for  client. 
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Keyboard  (continued) 


XLookupString 

XQueryKeymap 

XGetKeyboardMapping 

XChangeKeyboardMapping 

XRefreshKeyboardMapping 

XSe-tModifierMapping 

XGetModifierMapping 

XDeleteModifiermapEntry 

XInsertModifiermapEntry 

XNewModifiermap 

XFreeModifiermap 

XDisplayKeycodes 

Macros,  Display 


Map  a  key  event  to  ASCII  string,  keysym,  and  Compose- 

Status. 

Obtain  a  bit  vector  for  the  current  state  of  the  keyboard. 

Return  symbols  for  keycodes. 

Change  the  keyboard  mapping. 

Update  the  stored  modifier  and  keymap  information. 

Set  keycodes  to  be  used  as  modifiers  (Shift,  Control,  etc.). 

Obtain  modifier  key  mapping  (Shift,  Control,  etc.). 

Delete  an  entry  from  an  XModif  ierKeymap  structure. 

Add  a  new  entry  to  an  XModif  ierKeymap  structure. 

Create  a  keyboard  modifier  mapping  structure. 

Destroy  and  free  a  keyboard  modifier  mapping  structure. 

Returns  range  of  keycodes  used  by  server. 


AllPlanes 
BlackPixel 
BlackPixelOf Screen 

CellsOfScreen 
Connect ionNumber 

DefaultColormap 
DefaultColormapOf Screen 
DefaultDepth 
DefaultDepthOf Screen 
DefaultGC 

DefaultGCOf Screen 

DefaultRootWindow 
DefaultScreen 


DefaultScreenOf Display 
DefaultVisual 
DefaultVisualOf Screen 
DisplayCells 

DisplayHeight 

DisplayHeightMM 
DisplayOf Screen 
Display? lanes 


Return  an  unsigned  long  value  with  all  bits  set 
Return  a  black  pixel  value  on  the  default  colormap  of  screen. 
Return  the  black  pixel  value  in  the  default  colormap  of  the 
specified  screen. 

Return  the  number  of  colormap  cells  of  the  specified  screen. 
Return  the  connection  number  (file  descriptor  on  UNIX  sys 
tem). 

Return  the  default  colormap  on  the  specified  screen. 
Return  the  default  colormap  of  the  specified  screen. 
Return  the  depth  of  the  default  root  window  for  a  screen. 
Return  the  default  depth  of  the  specified  screen. 
Return  the  default  graphics  context  for  the  root  window  of  a 
screen. 

Return  the  default  graphics  context  (GC)  of  the  specified 
screen. 

Return  the  root  window  for  the  default  screen. 
Return  the  screen  integer;  the  last  segment  of  a  string  passed  to 
XOpenDi splay,  or  the  DISPLAY  environment  variable  if 
NULL  was  used. 

Return  the  default  screen  of  the  specified  display. 
Return  the  default  visual  structure  for  a  screen. 
Return  the  default  visual  of  the  specified  screen. 
Return  the  maximum  number  of  colormap  cells  on  the  con 
nected  display. 

Return  an  integer  that  describes  the  height  of  the  screen  in  pix 
els. 

Return  the  height  of  the  specified  screen  in  millimeters. 
Return  the  display  of  the  specified  screen. 
Return  the  number  of  planes  on  the  connected  display. 
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Macros,  Display  (continued) 


DisplayString 
DisplayType 

DisplayWidth 

DisplayWidthMM 

DoesBackingStore 


DoesSaveUnders 

dpyno 

EventMaskOf Screen 
HeightOfScreen 
HeightMMOfScreen 
Keyboard 

LastKnownRequest- 

Processed 
MaxCmapsOf Screen 

MinCmapsOf Screen 

NextRequest 
PlanesOf Screen 
ProtocolRevision 
ProtocolVersion 

QLength 

RootWindow 
RootWindowOf Screen 
ScreenCount 
XScreenNumberOf Screen 

ScreenOf Display 
ServerVendor 

Vendor Re lease 

WhitePixel 
WhitePixelOf Screen 

WidthOfScreen 

WidthMMOfScreen 

XDisplayMotionBufferSize 


Return  the  string  that  was  passed  to  XOpenDisplay  or  if 
that  was  NULL,  the  DISPLAY  variable. 
Return  the  connected  display  manufacturer,  as  defined  in 
<XlllXvendors.h>. 

Return  the  width  of  the  screen  in  pixels. 
Return  the  width  of  the  specified  screen  in  millimeters. 
Return  a  value  indicating  whether  the  screen  supports  backing 
stores.    Return   one   of  WhenMapped,   NotUseful,   or 
Always. 

Return  whether  the  screen  supports  save  unders.    True  or 
False. 

Return  the  file  descriptor  of  the  connected  display. 
Return  the  initial  root  event  mask  for  the  specified  screen. 
Return  the  height  of  the  specified  screen. 
Return  the  height  of  the  specified  screen  in  millimeters. 
Return  the  device  ID  for  the  main  keyboard  connected  to  the 
display. 

Return  the  serial  ID  of  the  last  known  protocol  request  to  have 
been  issued. 

Return  the  maximum  number  of  colormaps  supported  by  a 
screen. 

Return  the  minimum  number  of  colormaps  supported  by  a 
screen. 

Return  the  serial  ID  of  the  next  protocol  request  to  be  issued. 
Return  the  number  of  planes  in  a  screen. 
Return  the  minor  protocol  revision  number  of  the  X  server. 
Return  the  version  number  of  the  X  protocol  on  the  connected 
display. 

Return  the  current  length  of  the  input  queue  on  the  connected 
display. 

Return  the  ID  of  the  root  window. 
Return  the  root  window  of  the  specified  screen. 
Return  the  number  of  available  screens. 
Return  the  integer  corresponding  to  the  specified  pointer  to  a 
Screen  structure. 

Return  the  specified  screen  of  the  specified  display. 
Return  a  pointer  to  a  null-terminated  string  giving  some  identi 
fication  of  the  maker  of  the  X  server  implementation. 
Return  a  number  related  to  the  release  of  the  X  server  by  the 
vendor. 

Return  a  pixel  value  representing  white  in  default  colormap. 
Return  the  white  pixel  value  in  the  default  colormap  of  the 
specified  screen. 

Return  the  width  of  the  specified  screen. 
Return  the  width  of  the  specified  screen  in  millimeters. 
Return  size  of  server's  motion  history  buffer. 
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Macros,  Display  (continued) 


XListDepths  Return  a  list  of  the  depths  supported  on  this  server. 

XListPixmapFormats  Return  a  list  of  the  pixmap  formats  supported  on  this  server. 

XMaxRequestsize  Return  maximum  request  size  allowed  on  this  server. 

XResourceManagerString  Return  string  containing  user's  resource  database. 

Macros,  Image  Format 

BitmapBitOrder  Return  LeastSignif leant  or  MostSignif leant. 

Indicates  the  bit  order  in  BitmapUnit. 

BitmapPad  Each  scan  line  is  padded  to  a  multiple  of  bits  specified  by  the 

value  returned  by  this  macro. 

BitmapUnit  The  scan  line  is  quantized  (calculated)  in  multiples  of  this 

value. 

ByteOrder  Specifies  the  required  byte  order  for  images  for  each  scan  line 

unit  in  XYFormat  (bitmap)  or  for  each  pixel  value  in  ZFor- 
mat.  Possible  values  are  LSBFirst  orMSBFirst. 

i  mage  ByteOrder  Specifies  the  required  byte  order  for  images  for  each  scan  line 

unit  in  XYFormat  (bitmap)  or  for  each  pixel  value  in  z For 
mat.  Return  either  LSBFirst  orMSBFirst. 


Macros,  Keysym  Classification 


isCursorKey  Return  True  if  the  keysym  is  on  the  cursor  key. 

isFunctionKey  Return  True  if  the  keysym  is  on  the  function  keys. 

I  sKeypadKey  Return  T  rue  if  the  keysym  is  on  the  key  pad. 

isMiscFunct  ionKey  Return  True  if  the  keysym  is  on  the  miscellaneous  function  keys. 

isModif  ierKey  Return  True  if  the  keysym  is  on  the  modifier  keys. 

I  sPFKey  Return  T  rue  if  the  keysym  is  on  the  PF  keys. 

Mapping 


(see  Window  Mapping,  Keyboard,  or  Pointer) 
Output  Buffer 


<Flush  Rush  the  request  buffer. 

xsync  Flush  the  request  buffer  and  wait  for  all  events  to  be  processed 

by  the  server. 

Pointers 

XQueryPointer  Get  the  current  pointer  location. 

xwarpPointer  Move  the  pointer  to  another  point  on  the  screen. 

XGrabPointer  Grab  the  pointer. 

xungrabPointer  Release  the  pointer  from  grab. 
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Pointers  (continued) 


XGetPointerMapping 

XSetPointerMapping 

XGetPointerControl 

XChangePointerControl 

XChangeActivePointerGrab 


Get  the  pointer  button  mapping. 

Set  the  pointer  button  mapping. 

Get  the  current  pointer  preferences. 

Change  the  pointer  preferences. 

Change  the  parameters  of  an  active  pointer  grab. 


Properties 


XListProperties 

XDeleteProperty 

XChangeProperty 

XSetStandardProperties 

XRot a teWindowP roper ties 

XGetAtomName 

XGet Font Property 

XGetWindowProperty 

XInternAtom 

XGetTextProperty 

XSet Text Property 

XStringListToText Property 

XTextPropertyToStringList 

XFreeStringList 


Get  the  property  list  for  a  window. 

Delete  a  window  property. 

Change  a  property  associated  with  a  window. 

Set  the  minimum  set  of  properties  for  the  window  manager. 

Rotate  properties  in  the  properties  array. 

Get  a  name  for  a  given  atom. 

Get  a  font  property  given  its  atom. 

Obtain  the  atom  type  and  property  format  for  a  window. 

Return  an  atom  for  a  given  name  string. 

Read  a  TEXT  property. 

Write  a  TEXT  property. 

Convert  a  list  of  strings  to  an  XTextProperty  structure. 

Convert  an  XTextProperty  to  a  list  of  strings. 

Free  memory  allocated  by  XTextPropertyToStringList. 


Regions 


XCreateRegion 

XDestroyRegion 

XEmptyRegion 

XPolygonRegion 

XPointlnRegion 

XRectlnRegion 

XUnionRectWithRegion 

XClipBox 

XOf fsetRegion 

XShrinkRegion 

XEqualRegion 

XSetRegion 

XSubtract Region 
XInter sect Region 
XUnionRegion 
XXorRegion 


Create  a  new  empty  region. 

Deallocate  storage  associated  with  a  region. 

Determine  if  a  region  is  empty. 

Generate  a  region  from  points. 

Determine  if  a  point  resides  in  a  region. 

Determine  if  a  rectangle  resides  in  a  region. 

Add  a  rectangle  to  a  region. 

Generate  the  smallest  rectangle  enclosing  a  region. 

Change  offset  of  a  region. 

Reduce  the  size  of  a  region. 

Determine  if  two  regions  have  the  same  size,  offset,  and  space. 

Set  clip_mask  of  the  graphics  context  to  the  specified 

region. 

Subtract  one  region  from  another. 

Compute  the  intersection  of  two  regions. 

Compute  the  union  of  two  regions. 

Calculate  the  difference  between  the  union  and  intersection  of 

2  regions. 
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Resource  Manager 


XrmDestroyDat abase 

XrmGetFileDatabase 

XrmGetResource 

XrmGetStringDat abase 

Xrmlnitialize 

XrmMergeDat abases 

XrmParseCommand 

XrmPutFileDat abase 

XrmPutLineResource 

XrmPutResource 

XrmPutStringResource 

XrmQGetResource 

XrmQGetSearchList 

XrmQGetSearchResource 

XrmQPut Resource 

XrmQPutStringResource 

XrmQuarkToString 

XrmStringToBinding- 

QuarkList 

XrmStringToQuarkList 
XrmStringToQuark 
XrmUniqueQuark 
Xpermalloc 
XResourceManager String 


Destroy  a  resource  database. 

Retrieve  a  database  from  a  file. 

Get  a  resource  from  name  and  class  as  strings. 

Create  a  database  from  a  string. 

Initialize  the  resource  manager. 

Merge  the  contents  of  one  database  with  another. 

Load  a  resource  database  from  command  line  arguments. 

Store  a  database  in  a  file. 

Add  a  resource  entry  given  as  a  string  of  name  and  value. 

Store  a  resource  into  a  database. 

Add  a  resource  that  is  specified  as  a  string. 

Get  a  resource  from  name  and  class  as  quarks. 

Return  a  list  of  database  levels. 

Search  resource  database  levels  for  a  given  resource. 

Store  a  resource  into  a  database  using  quarks. 

Add  a  string  resource  value  to  a  database  using  quarks. 

Convert  a  quark  to  a  string. 

Convert  a  key  string  to  a  binding  list  and  a  quark  list. 

Convert  a  key  string  to  a  quark  list. 

Convert  a  string  to  a  quark. 

Allocate  a  new  quark. 

Allocate  memory  never  to  be  freed. 

Get  user's  database  set  with  xrdb  from  Display  structure. 


Save  Set 


XAddToSaveSet 

XRemoveFromSaveSet 

XChangeSaveSet 


Add  a  window  to  the  client's  save-set. 

Remove  a  window  from  the  client's  save-set. 

Add  or  remove  a  window  to  or  from  the  client's  save-set. 


Screen  Saver 


XActivate Screen Saver 

XForceScreenSaver 

XResetScreenSaver 

XGetScreenSaver 

XSetScreenSaver 


Activate  screen  blanking. 

Turn  the  screen  saver  on  or  off. 

Reset  the  screen  saver. 

Get  the  current  screen  saver  parameters. 

Set  the  parameters  of  the  screen  saver. 


Selections 


XGet Select ionOwner 
XSetSelectionOwner 
XConvert Select ion 


Return  the  owner  of  a  selection. 
Set  the  owner  of  a  selection. 
Use  the  value  of  a  selection. 
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Server  Specifications 

(see  Display  Specifications) 

Standard  Geometry 


XGeometry 
XWMGeometry 
XParseGeometry 
XTranslateCoordinates 


Calculate  window  geometry  given  user  geometry  string  and 

default  geometry.  Superceded  in  R4  by  XWMGeometry. 

Calculate  window  geometry  given  user  geometry  string  and 

default  geometry. 

Generate  position  and  size  from  standard  window  geometry 

string. 

Change  the  coordinate  system  from  one  window  to  another. 


Text 


XDrawImageString 
XDrawImageStr ingl 6 
XDrawString 
XDrawStringlG 
XDrawText 
XDrawTextl6 
XQueryText Extents 
XQueryTextExtentsl6 

XTextExtents 
XTextExtentslG 
XTextWidth 
XTextWidthlG 


Draw  8-bit  image  text  characters. 
Draw  16-bit  image  text  characters. 
Draw  an  8-bit  text  string,  foreground  only. 
Draw  two-byte  text  strings. 
Draw  8-bit  polytext  strings. 
Draw  16-bit  polytext  strings. 
Query  the  server  for  string  and  font  metrics. 
Query  the  server  for  string  and  font  metrics  of  a  16-bit  charac 
ter  string. 

Get  string  and  font  metrics. 

Get  string  and  font  metrics  of  a  16-bit  character  string. 
Get  the  width  in  pixels  of  an  8-bit  character  string. 
Get  the  width  in  pixels  of  a  16-bit  character  string. 


Tile,  Pixmap,  Stipple  and  Bitmap 


XCreatePixmap 

XFreePixmap 

XQueryBestSize 

XQueryBest Stipple 

XQueryBestTile 

XSetTile 

XSetWindowBorderP ixmap 

XSetWindowBackgroundPixmap 

XReadBitmapFile 

XWriteBitmapFile 

XCreateBitmapFromData 

XCreatePixmapFromBitmapData 

XListPixmapFormats 


Create  a  pixmap. 

Free  a  pixmap  ID. 

Obtain  the  "best"  supported  cursor,  tile,  or  stipple  size. 

Obtain  the  best  supported  stipple  shape. 

Obtain  the  best  supported  fill  tile  shape. 

Set  the  fill  tile  in  a  graphics  context. 

Change  a  window  border  tile  attribute  and  repaint  the  border. 

Change  the  background  tile  attribute  of  a  window. 

Read  a  bitmap  from  disk. 

Write  a  bitmap  to  a  file. 

Create  a  bitmap  from  XI 1  bitmap  format  data. 

Create  a  pixmap  with  depth  from  bitmap  data. 

Read  supported  pixmap  formats  from  Display  structure. 
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User  Preferences 


XAutoRepeatOff 

XAutoRepeatOn 

XBell 

XGetDefault 

XGetPointer Control 

XGetKeyboardControl 

XChangeKeyboardControl 


Turn  off  the  keyboard  auto-repeat  keys. 

Turn  on  the  keyboard  auto-repeat  keys. 

Ring  the  bell  (Control  G). 

Scan  the  user  preferences  for  program  name  and  options. 

Get  the  current  pointer  preferences. 

Obtain  a  list  of  the  current  keyboard  preferences. 

Change  the  keyboard  preferences. 


Visuals 


XGetVisuallnfo 
XMatchVisuallnfo 

DefaultVisual 
XVisuallDFromVisual 


Find  a  visual  information  structure  that  matches  the  specified 

template. 

Obtain  the  visual  information  that  matches  the  desired  depth 

and  class. 

Return  the  default  visual  structure  for  a  screen. 

Get  resource  ID  from  a  visual  structure. 


Window  Attributes 


XGetWindowAt tributes 
XChangeWindowAttributes 
XSetWindowBackground 
XSetWindowBackgroundP ixmap 
XSetWindowBorder 

XSetWindowBorderP ixmap 

XSetWindowColormap 

XDefineCursor 

XGet Geometry 

XSelectlnput 


Obtain  the  current  attributes  of  window. 

Set  window  attributes. 

Set  the  background  pixel  attribute  of  a  window. 

Change  the  background  tile  attribute  of  a  window. 

Change  a  window  border  attribute  to  the  specified  pixel  value 

and  repaint  the  border. 

Change  a  window  border  tile  attribute  and  repaint  the  border. 

Set  the  colormap  for  a  specified  window. 

Assign  a  cursor  to  a  window. 

Obtain  the  current  geometry  of  drawable. 

Select  the  event  types  to  be  sent  to  a  window. 


Window  Configuration 


XMoveWindow 

XResizeWindow 

XMoveResizeWindow 

XSetWindowBorderWidth 

XRestackWindows 

XConfigureWindow 

XGetGeometry 
XReconfigureWMWindow 


Move  a  window. 

Change  a  window's  size. 

Change  the  size  and  position  of  a  window. 

Change  the  border  width  of  a  window. 

Change  the  stacking  order  of  siblings. 

Change  the  window  position,  size,  border  width,  or  stacking 

order. 

Obtain  the  current  geometry  of  drawable. 

Change  top-level  window  position,  size,  border  width,  or 

stacking  order. 
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Window  Existence 


XCreateSimpleWindow 
XCreateWindow 
XDestroySubwindows 
XDestroy Window 


Create  an  unmapped  inputOutput  subwindow. 

Create  a  window  and  set  attributes. 

Destroy  all  subwindows  of  a  window. 

Unmap  and  destroy  a  window  and  all  subwindows. 


Window  Manager  Hints 


XGetClassHint 

XSetClassHint 

XGetNormalHints 

XSetNormalHints 

XGetSizeHints 

XSetSizeHints 

XGet Trans lent ForHint 

XSetTransientForHint 

XGetWMHints 

XSetWMHints 

XGetZoomHints 

XSetZoomHints 

XFetchName 

XStoreName 

XGetlconName 
XSetlconName 

XGetlconSizes 
XSetlconSizes 
XSetCommand 

XAllocClassHint 

XAllocIconSize 

XAllocSizeHints 

XAllocStandardColormap 

XAllocWMHints 


Get  the  XA_WM_CLASS  property  of  a  window.  Obsolete  in 

R4. 

Set  the  XA_WM_CLASS  property  of  a  window.  Obsolete  in 

R4. 

Get  the  size  hints  property  of  a  window  in  normal  state  (not 

zoomed  or  iconified).  Obsolete  in  R4. 

Set  the  size  hints  property  of  a  window  in  normal  state  (not 

zoomed  or  iconified).  Obsolete  in  R4. 

Read  any  property  of  type  XA_WM_SIZE_HINTS.  Obsolete 

inR4. 

Set  the  value  of  any  property  of  type  XA_WM_- 

SIZE_HINTS.  Obsolete  in  R4. 

Get  the  XA_WM_TRANSIENT_FOR  property  of  a  window. 

Set  the  XA_WM_TRANSIENT_FOR  property  of  a  window. 

Read  a  window  manager  hints  property. 

Set  a  window  manager  hints  property. 

Read  the  size  hints  property  of  a  zoomed  window.  Obsolete  in 

R4. 

Set  the  size  hints  property  of  a  zoomed  window.  Obsolete  in 

R4. 

Get  a  window's  name  (XA_WM_NAME  property).   Obsolete  in 

R4. 

Assign  a  name  to  a  window  for  the  window  manager.  Obsolete 

inR4. 

Get  the  name  to  be  displayed  in  an  icon.  Obsolete  in  R4. 

Set  the  name  to  be  displayed  in  a  window's  icon.  Obsolete  in 

R4. 

Get  preferred  icon  sizes. 

Set  the  value  of  the  XA_WM_ICON_SIZE  property. 

Set  the  XA_WM_COMMAND  property  (command  line  arguments). 

Obsolete  in  R4. 

Allocate  and  zero  fields  in  XClassHint  structure. 

Allocate  and  zero  fields  in  xlconSize  structure. 

Allocate  and  zero  fields  in  xsizeHints  structure. 

Allocate  and  zero  fields  in  XStandardColormap  structure. 

Allocate  and  zero  fields  in  xwMHints  structure. 
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Window  Manager  Hints  (continued) 


XGetRGBColormaps 
XSetRGBColormaps 

XGetWMClientMachine 
XSetWMClientMachine 
XGetWMIconName 

XSetWMIconName 

XGetWMProtocols 
XSetWMProtocols 
XGetWMNormalHints 

XSetWMNormalHints 
XSetWMSizeHints 

XSetWMColormapWindows 
XGetWMColormapWindows 
XSetWMProperties 

XSetWMName 
XGetWMName 


Read  standard  colormap  property.    Replaces  XGetStan- 

dardColormap. 

Write  standard  colormap  property.   Replaces  xsetstan- 

dardColormap. 

Read  WM_CLIENT_MACHINE  property. 

Write  WM_CLIENT_MACHINE  property. 

Read    XA_WM_ICON_NAME    property.    Replaces    XGet- 

IconName. 

Write    XA_WM_ICON_NAME    property.    Replaces    xset- 

IconName. 

Read  WM_PROTOCOLS  property. 

Write  WM_PROTOCOLS  property. 

Read  XA_WM_NORMAL_HINTS  property.  Replaces  xGet- 

NormalHints. 

Write  XA_WM_NORMAL_HINTS  property.  Replaces  XSet- 

NormalHints. 

Write  XA_WM_SIZE_HINTS  property.    Replaces   xset- 

SizeHints. 

Write  WM_COLORMAP_WINDOWS  property. 

Read  WM_COLORMAP_WINDOWS  property. 

Write    all    standard    properties.     Replaces     XSetStan- 

dardProperties. 

Write  XA_WM_NAME  property.  Replaces  XStoreName. 

Read  XA_WM_NAME  property.  Replaces  XFetchName. 


Window  Manipulation 


XLowerWindow 

XRaiseWindow 

XCirculateSubwindows 

XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XQueryTree 

XRepar en t Window 

XMoveWindow 

XResizeWindow 

XMoveResizeWindow 

XSetWindowBorderWidth 

XRestackWindows 

XConfigureWindow 

XlconifyWindow 

XWithdrawWindow 

XReconfigureWMWindow 


Lower  a  window  in  the  stacking  order. 

Raise  a  window  to  the  top  of  the  stacking  order. 

Circulate  the  stacking  order  of  children  up  or  down. 

Circulate  the  bottom  child  to  the  top  of  the  stacking  order. 

Circulate  the  top  child  to  the  bottom  of  the  stacking  order. 

Return  a  list  of  children,  parent,  and  root. 

Change  a  window's  parent 

Move  a  window. 

Change  a  window's  size. 

Change  the  size  and  position  of  a  window. 

Change  the  border  width  of  a  window. 

Change  the  stacking  order  of  siblings. 

Change  the  window  position,  size,  border  width,  or  stacking 

order. 

Inform  window  manager  that  a  top-level  window  should  be 

iconified. 

Inform  window  manager  that  a  top-level  window  should  be 

unmapped. 

Reconfigure  a  top-level  window. 
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Window  Mapping 


XMapRaised 

XMapSubwindows 

XMapWindow 

XUnmapSubwindows 

XUnmapWindow 

XlconifyWindow 

XWithdrawWindow 


Map  a  window  on  top  of  its  siblings. 

Map  all  subwindows. 

Map  a  window. 

Unmap  all  subwindows  of  a  given  window. 

Unmap  a  window. 

Inform  window  manager  that  a  top-level  window  should  be  iconified. 

Inform  window  manager  that  a  top-level  window  should  be  unmapped. 


A.2  Alphabetical  Listing  of  Routines 


Table  A-1.  Alphabetical  Listing  of  Routines 


Routine 


Description 


XActivateScreenSaver 

XAddHost 

XAddHosts 

XAddPixel 

XAddToSaveSet 

XAllocClassHint 

XAllocIconSize 

XAllocSizeHints 

XAllocStandardColormap 

XAllocWMHints 

XAllocColor 

XAllocColorCells 
XAllocColorPlanes 
XAllocNamedColor 
XAllowEvents 

XAutoRepeatOff 

XAutoRepeatOn 

XBell 

XChangeActivePointerGrab 

XChangeGC 

XChangeKeyboardControl 

XChangeKeyboardMapping 

XChangePointerControl 

XChangeProperty 

XChangeSaveSet 

XChangeWindowAttributes 

XChecklfEvent 

XCheckMaskEvent 


Activate  screen  blanking. 
Add  a  host  to  the  access  control  list. 
Add  multiple  hosts  to  the  access  control  list. 
Add  a  constant  value  to  every  pixel  value  in  an  image. 
Add  a  window  to  the  client's  save-set. 
Allocate  and  zero  fields  in  XClassHint  structure. 
Allocate  and  zero  fields  inxiconSize  structure. 
Allocate  and  zero  fields  in  XSizeHints  structure. 
Allocate  and  zero  fields  in  XStandardColormap  structure. 
Allocate  and  zero  fields  in  XWMHints  structure. 
Allocate  a  read-only  colormap  cell  with  closest  hardware- 
supported  color. 

Allocate  read/write  (nonshared)  colorcells. 
Allocate  read/write  (nonshareable)  color  planes. 
Allocate  a  read-only  colorcell  from  color  name. 
Control  the  behavior  of  keyboard  and  pointer  events  when 
these  resources  are  grabbed. 
Turn  off  the  keyboard  auto-repeat  keys. 
Turn  on  the  keyboard  auto-repeat  keys. 
Ring  the  bell  (Control  G). 
Change  the  parameters  of  an  active  pointer  grab. 
Change  the  components  of  a  given  graphics  context. 
Change  the  keyboard  preferences  such  as  key  click. 
Change  the  keyboard  mapping. 
Change  the  pointer  preferences. 
Change  a  property  associated  with  a  window. 
Add  or  remove  a  window  to  or  from  the  client's  save-set 
Set  window  attributes. 

Check  the  event  queue  for  a  matching  event. 
Remove  the  next  event  that  matches  mask;  don't  wait. 
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Table  A-1.  Alphabetical  Listing  of  Routines  (continued) 


Routine 


Description 


XCheckTypedEvent 

XCheckTypedWindowEvent 

XCheckWindowEvent 

XCirculateSubwindows 
XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XClearArea 
XClearWindow 
XClipBox 
XCloseDisplay 
XConf igureWindow 

XConvert Select ion 

XCopyArea 

XCopyColormapAndFree 

XCopyGC 

XCopyPlane 

XCreateAssocTable 
XCreateBitmapFromData 
XCreateColormap 
XCreateFont Cursor 
XCreateGC 

XCreateGlyphCursor 
XCreate Image 
XCreatePixmap 
XCreatePixmapCursor 
XCreatePixmapFrom- 

BitmapData 
XCreateRegion 
XCreateSimpleWindow 
XCreateWindow 
XDefineCursor 
XDeleteAssoc 
XDeleteContext 
XDeleteModifiermapEntry 
XDeleteProperty 
XDestroyAssocTable 
XDestroylmage 
XDestroyRegion 


Return  the  next  event  in  queue  that  matches  event  type; 

Return  the  next  event  in  queue  matching  type  and  window. 

Remove  the  next  event  matching  both  passed  window  and 

passed  mask;  don't  wait. 

Circulate  the  stacking  order  of  children  up  or  down. 

Circulate  the  bottom  child  to  the  top  of  the 

stacking  order. 

Circulate  the  top  child  to  the  bottom  of  the 

stacking  order. 

Clear  a  rectangular  area  in  a  window. 

Clear  an  entire  window. 

Generate  the  smallest  rectangle  enclosing  a  region. 

Disconnect  a  client  program  from  an  X  server  and  display. 

Change  the  window  position,  size,  border  width,  or  stacking 

order. 

Use  the  value  of  a  selection. 

Copy  an  area  of  a  drawable. 

Copy  a  colormap  and  return  a  new  colormap  ID. 

Copy  a  graphics  context. 

Copy  a  single  plane  of  a  drawable  into  a  drawable  with  depth, 

applying  pixel  values. 

Create  a  new  association  table  (X10). 

Create  a  bitmap  from  XI 1  bitmap  format  data. 

Create  a  colormap. 

Create  a  cursor  from  the  standard  cursor  font 

Create  a  new  graphics  context  for  a  given  screen  with  the  depth 

of  the  specified  drawable. 

Create  a  cursor  from  font  glyphs. 

Allocate  memory  for  an  x Image  structure. 

Create  a  pixmap. 

Create  a  cursor  from  two  bitmaps. 

Create  a  pixmap  with  depth  from  bitmap  data. 

Create  a  new  empty  region. 

Create  an  unmapped  inputOutput  window. 

Create  a  window  and  set  attributes. 

Assign  a  cursor  to  a  window. 

Delete  an  entry  from  an  association  table. 

Delete  a  context  entry  for  a  given  window  and  type. 

Delete  an  entry  from  an  XModif  ierKeymap  structure. 

Delete  a  window  property. 

Free  the  memory  allocated  for  an  association  table. 

Deallocate  memory  associated  with  an  image. 

Deallocate  storage  associated  with  a  region. 
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Table  A-1.  Alphabetical  Listing  of  Routines  (continued) 


Routine 


Description 


XDestroySubwindows 

XDestroyWindow 

XDisableAccessControl 

XDisplayKeycodes 

XDisplayMotionBuf ferSize 

XDisplayName 

XDraw 

XDrawArc 

XDrawArcs 

XDrawFilled 

XDrawImageString 

XDrawImageStringlG 

XDrawLine 

XDrawLines 

XDrawPoint 

XDrawPoints 

XDrawRect angle 

XDrawRect angles 

XDrawSegments 

XDrawString 

XDrawStringl6 

XDrawText 

XDrawTextlG 

XEmptyRegion 

XEnableAccessControl 

XEqualRegion 

XEventsQueued 

XFetchBuffer 

XFetchBytes 

XFetchName 

XFillArc 

XFillArcs 

XFillPolygon 

XFillRectangle 

XFillRectangles 

XFindContext 

XFlush 

XForceScreenSaver 

XFree 

XFreeColormap 

XFreeColors 

XFreeCursor 


Destroy  all  subwindows  of  a  window. 

Unmap  and  destroy  a  window  and  all  subwindows. 

Allow  access  from  any  host 

Returns  range  of  keycodes  used  by  server. 

Return  size  of  server's  motion  history  buffer. 

Report  the  display  name  when  connection  to  a  display  fails. 

Draw  a  polyline  or  curve  between  vertex  list  (from  X10). 

Draw  an  arc  fitting  inside  a  rectangle. 

Draw  multiple  arcs. 

Draw  a  filled  polygon  or  curve  from  vertex  list  (from  X10). 

Draw  8-bit  image  text  characters. 

Draw  16-bit  image  text  characters. 

Draw  a  line  between  two  points. 

Draw  multiple  connected  lines. 

Draw  a  point. 

Draw  multiple  points. 

Draw  an  outline  of  a  rectangle. 

Draw  the  outlines  of  multiple  rectangles. 

Draw  multiple  disjoint  lines. 

Draw  an  8-bit  text  string,  foreground  only. 

Draw  two-byte  text  strings. 

Draw  8-bit  polytext  strings. 

Draw  16-bit  polytext  strings. 

Determine  if  a  region  is  empty. 

Use  access  control  list  to  allow  or  deny  connection  requests. 

Determine  if  two  regions  have  the  same  size,  offset,  and  shape. 

Check  the  number  of  events  in  the  event  queue. 

Return  data  from  a  cut  buffer. 

Return  data  from  cut  buffer  0. 

Get  a  window's  name  (XA_WM_NAME  property). 

Fill  an  arc. 

Fill  multiple  arcs. 

Fill  a  polygon. 

Fill  a  rectangular  area. 

Fill  multiple  rectangular  areas. 

Get  data  from  the  context  manager  (not  graphics  context). 

Flush  the  request  buffer  (display  all  queued  requests). 

Turn  the  screen  saver  on  or  off. 

Free  specified  in-memory  data  created  by  an  Xlib  function. 

Delete  a  colormap  and  install  the  default  colormap. 

Free  colormap  cells  or  planes. 

Destroy  a  cursor. 
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Table  A-1.  Alphabetical  Listing  of  Routines  (continued) 


Routine 


Description 


XCheckTypedEvent 

XCheckTypedWindowEvent 

XCheckWindowEvent 

XCirculateSubwindows 
XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XClearArea 

XClearWindow 

XClipBox 

XCloseDisplay 

XConfigureWindow 

XConvertSelection 

XCopyArea 

XCopyColormapAndFree 

XCopyGC 

XCopyPlane 

XCreateAssocTable 

XCreateBitmapFromData 

XCreateColormap 

XCr eat eFont Cursor 

XCreateGC 

XCreateGlyphCursor 
XCr eate Image 
XCreatePixmap 
XCreatePixmapCursor 
XCreatePixmapFrom- 

BitmapData 
XCreateRegion 
XCreateSimpleWindow 
XCreateWindow 
XDefineCursor 
XDeleteAssoc 
XDeleteContext 
XDeleteModifiermapEntry 
XDeleteProperty 
XDestroyAssocTable 
XDestroylmage 
XDestroyRegion 


Return  the  next  event  in  queue  that  matches  event  type; 

Return  the  next  event  in  queue  matching  type  and  window. 

Remove  the  next  event  matching  both  passed  window  and 

passed  mask;  don't  wait. 

Circulate  the  stacking  order  of  children  up  or  down. 

Circulate  the  bottom  child  to  the  top  of  the 

stacking  order. 

Circulate  the  top  child  to  the  bottom  of  the 

stacking  order. 

Clear  a  rectangular  area  in  a  window. 

Clear  an  entire  window. 

Generate  the  smallest  rectangle  enclosing  a  region. 

Disconnect  a  client  program  from  an  X  server  and  display. 

Change  the  window  position,  size,  border  width,  or  stacking 

order. 

Use  the  value  of  a  selection. 

Copy  an  area  of  a  drawable. 

Copy  a  colormap  and  return  a  new  colormap  ID. 

Copy  a  graphics  context. 

Copy  a  single  plane  of  a  drawable  into  a  drawable  with  depth, 

applying  pixel  values. 

Create  a  new  association  table  (X10). 

Create  a  bitmap  from  XI 1  bitmap  format  data. 

Create  a  colormap. 

Create  a  cursor  from  the  standard  cursor  font 

Create  a  new  graphics  context  for  a  given  screen  with  the  depth 

of  the  specified  drawable. 

Create  a  cursor  from  font  glyphs. 

Allocate  memory  for  an  X Image  structure. 

Create  a  pixmap. 

Create  a  cursor  from  two  bitmaps. 

Create  a  pixmap  with  depth  from  bitmap  data. 

Create  a  new  empty  region. 

Create  an  unmapped  inputOutput  window. 

Create  a  window  and  set  attributes. 

Assign  a  cursor  to  a  window. 

Delete  an  entry  from  an  association  table. 

Delete  a  context  entry  for  a  given  window  and  type. 

Delete  an  entry  from  an  XModif  ierKeymap  structure. 

Delete  a  window  property. 

Free  the  memory  allocated  for  an  association  table. 

Deallocate  memory  associated  with  an  image. 

Deallocate  storage  associated  with  a  region. 
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Table  A-1.  Alphabetical  Listing  of  Routines  (continued) 


Routine 


Description 


XDestroySubwindows 

XDestroyWindow 

XDisableAccessControl 

XDisplayKeycodes 

XDisplayMotionBufferSize 

XDisplayName 

XDraw 

XDrawArc 

XDrawArcs 

XDrawFilled 

XDrawImageString 

XDrawImageString 16 

XDrawLine 

XDrawLines 

XDrawPoint 

XDrawPoints 

XDrawRect angle 

XDr a wRect angles 

XDrawSegments 

XDrawString 

XDrawStringlG 

XDrawText 

XDrawTextl6 

XEmptyRegion 

XEnableAccessControl 

XEqualRegion 

XEventsQueued 

XFetchBuffer 

XFetchBytes 

XFetchName 

XFillArc 

XFillArcs 

XFillPolygon 

XFillRectangle 

XFillRectangles 

XFindContext 

XFlush 

XForceScreenSaver 

XFree 

XFreeColormap 

XFreeColors 

XFreeCursor 


Destroy  all  subwindows  of  a  window. 

Unmap  and  destroy  a  window  and  all  subwindows. 

Allow  access  from  any  host 

Returns  range  of  keycodes  used  by  server. 

Return  size  of  server's  motion  history  buffer. 

Report  the  display  name  when  connection  to  a  display  fails. 

Draw  a  polyline  or  curve  between  vertex  list  (from  X10). 

Draw  an  arc  fitting  inside  a  rectangle. 

Draw  multiple  arcs. 

Draw  a  filled  polygon  or  curve  from  vertex  list  (from  X10). 

Draw  8-bit  image  text  characters. 

Draw  16-bit  image  text  characters. 

Draw  a  line  between  two  points. 

Draw  multiple  connected  lines. 

Draw  a  point. 

Draw  multiple  points. 

Draw  an  outline  of  a  rectangle. 

Draw  the  outlines  of  multiple  rectangles. 

Draw  multiple  disjoint  lines. 

Draw  an  8-bit  text  string,  foreground  only. 

Draw  two-byte  text  strings. 

Draw  8-bit  polytext  strings. 

Draw  16-bit  polytext  strings. 

Determine  if  a  region  is  empty. 

Use  access  control  list  to  allow  or  deny  connection  requests. 

Determine  if  two  regions  have  the  same  size,  offset,  and  shape. 

Check  the  number  of  events  in  the  event  queue. 

Return  data  from  a  cut  buffer. 

Return  data  from  cut  buffer  0. 

Get  a  window's  name  (XA_WM_NAME  property). 

Fill  an  arc. 

Fill  multiple  arcs. 

Fill  a  polygon. 

Fill  a  rectangular  area. 

Fill  multiple  rectangular  areas. 

Get  data  from  the  context  manager  (not  graphics  context). 

Flush  the  request  buffer  (display  all  queued  requests). 

Turn  the  screen  saver  on  or  off. 

Free  specified  in-memory  data  created  by  an  Xlib  function. 

Delete  a  colormap  and  install  the  default  colormap. 

Free  colormap  cells  or  planes. 

Destroy  a  cursor. 
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Table  A-1.  Alphabetical  Listing  of  Routines  (continued) 


Routine 


Description 


XFreeExtensionList 

XFreeFont 

XFreeFontlnfo 

XFreeFontNames 

XFreeFontPath 

XFreeGC 

XFreeModifiermap 

XFreePixmap 

XFreeStringList 

XGContextFromGC 
XGeometry 

XGetAtomName 

XGetClassHint 

XGetDefault 

XGetErrorDatabaseText 

XGetErrorText 

XGetFontPath 

XGetFontProperty 

XGetGeometry 

XGetGCValues 

XGetlconName 

XGetlconSizes 

XGetlmage 

XGetlnputFocus 

XGetKeyboardControl 

XGetKeyboardMapping 

XGetModifierMapping 

XGetMotionE vents 

XGetNormalHints 

XGetPixel 

XGet Point erControl 

XGetPointerMapping 

XGetRGBColormaps 

XGetScreenSaver 
XGet Select ionOwner 
XGetSizeHints 
XGetStandardColormap 


Free  memory  allocated  for  a  list  of  installed 

extensions  to  X. 

Unload  a  font  and  free  storage  for  the  font  structure. 

Free  multiple  font  information  arrays. 

Free  the  font  name  array. 

Free  the  memory  allocated  by  XGetFontPath. 

Free  a  graphics  context. 

Destroy  and  free  a  keyboard  modifier  mapping  structure. 

Free  a  pixmap  ID. 

Free  memory  allocated  by  XTextProperty- 

ToStringList. 

Obtain  the  GContext  (resource  ID)  associated 

with  the  specified  graphics  context. 

Calculate  window  geometry  given  user  geometry  string 

and  default  geometry. 

Get  a  name  for  a  given  atom. 

Get  the  XA_WM_CLASS  property  of  a  window. 

Scan  the  user  preferences  for  program  name  and  options. 

Obtain  error  messages  from  the  error  database. 

Obtain  a  description  of  error  code. 

Get  the  current  font  search  path. 

Get  a  font  property  given  its  atom. 

Obtain  the  current  geometry  of  drawable. 

Get  GC  component  values  from  Xlib's  GC  cache. 

Get  the  name  to  be  displayed  in  an  icon. 

Get  preferred  icon  sizes. 

Place  contents  of  a  rectangle  from  drawable  into  an  image. 

Return  the  current  keyboard  focus  window. 

Obtain  a  list  of  the  current  keyboard  preferences. 

Return  symbols  for  keycodes. 

Obtain  a  mapping  of  modifier  keys  (Shift,  Control,  etc.). 

Get  pointer  motion  events. 

Get  the  size  hints  property  of  a  window  in  normal  state  (not 

zoomed  or  iconified). 

Obtain  a  single  pixel  value  from  an  image. 

Get  the  current  pointer  preferences. 

Get  the  pointer  button  mapping. 

Read  standard  colormap  property. 

Replaces  XGetStandardColormap. 

Get  the  current  screen  saver  parameters. 

Return  the  owner  of  a  selection. 

Read  any  property  of  type  XA_WM_SIZE_HINTS. 

Get  the  standard  colormap  property. 
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Table  A-1.  Alphabetical  Listing  of  Routines  (continued) 


Routine 


Description 


XGetSublmage 

XGetTextProperty 

XGetTransientForHint 

XGetVisuallnfo 

XGetWindowAttributes 

XGetWindowProperty 

XGetWMClientMachine 

XGetWMColormapWindows 

XGetWMHints 

XGetWMIconName 

XGetWMName 
XGetWMNormalHints 

XGetWMProtocols 
XGetWMSizeHints 

XGetZoomHints 

XGrabButton 

XGrabKey 

XGrabKeyboard 

XGrabPointer 

XGrabServer 

XlconifyWindow 

XlfEvent 

XInsertModifiermapEntry 

XInstallColormap 

XInternAtom 

XIntersectRegion 

XKeycodeToKeysym 

XKeysymToKeycode 

XKeysymToString 

XKillClient 

XListDepths 

XListExtensions 

XListFonts 

XListFontsWithlnfo 

XListHosts 

XListlnstalledColormaps 

XListPixmapFormats 


Copy  a  rectangle  in  drawable  to  a  location  within  the 

pre-existing  image. 

Read  a  TEXT  property. 

Get  the  XA_WM_TRANS  IENT_FOR  property  of  a  window. 

Find  a  visual  information  structure  that  matches  the 

specified  template. 

Obtain  the  current  attributes  of  window. 

Obtain  the  atom  type  and  property  format  for  a  window. 

Read  WM_CLIENT_MACHINE  property. 

Read  WM_COLORMAP_WINDOWS  property. 

Read  a  window  manager  hints  property. 

Read  XA_WM_ICON_NAME  property. 

Replaces  XGetlconName. 

Read  XA_WM_NAME  property.  Replaces  XFetchName. 

Read  XA_WM_NORMAL_HINTS  property.  Replaces 

XGetNormalHints. 

Read  WM_PROTOCOLS  property. 

Read  XA_WM_SIZE_HINTS  property.  Replaces 

XGetSizeHints. 

Read  the  size  hints  property  of  a  zoomed  window. 

Grab  a  pointer  button. 

Grab  a  key. 

Grab  the  keyboard. 

Grab  the  pointer. 

Grab  the  server. 

Inform  window  manager  that  a  top-level  window  should 

be  iconified. 

Wait  for  matching  event 

Add  a  new  entry  to  an  XModif  ierKeymap  structure. 

Install  a  colormap. 

Return  an  atom  for  a  given  name  string. 

Compute  the  intersection  of  two  regions. 

Convert  a  keycode  to  a  keysym. 

Convert  a  keysym  to  the  appropriate  keycode. 

Convert  a  keysym  symbol  to  a  string. 

Destroy  a  client  or  its  remaining  resources. 

Return  a  list  of  the  depths  supported  on  this  server. 

Return  a  list  of  all  extensions  to  X  supported  by  the  server. 

Return  a  list  of  the  available  font  names. 

Obtain  the  names  and  information  about  loaded  fonts. 

Obtain  a  list  of  hosts  having  access  to  this  display. 

Get  a  list  of  installed  colormaps. 

Return  a  list  of  the  pixmap  formats  supported  on 

this  server. 
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Table  A-1.  Alphabetical  Listing  of  Routines  (continued) 


Routine 


Description 


XrmQuarkToString 
XrmStringToBinding- 

QuarkList 
XrmStringToQuark 
XrmStringToQuarkList 
XrmUniqueQuark 
XRotateBuffers 
XRotateWindowProperties 
XSaveContext 

XSelectlnput 

XSendEvent 

XSetAccessControl 

XSetAfterFunction 

XSetArcMode 

XSet Background 

XSetClassHint 

XSetClipMask 

XSetClipOrigin 

XSetClipRectangles 

XSetCloseDownMode 

XSetCommand 

XSetDashes 

XSetErrorHandler 

XSetFillRule 

XSetFillStyle 

XSetFont 

XSetFontPath 

XSet Foreground 

XSetFunction 

XSetGraphicsExposures 

XSetlconName 

XSetlconSizes 

XSetlnputFocus 

XSetlOErrorHandler 

XSetLineAttributes 

XSetModifierMapping 

XSetNormalHints 

XSetPlaneMask 
XSet Point erMapping 


Convert  a  quark  to  a  string. 

Convert  a  key  string  to  a  binding  list  and  a  quark 

list. 

Convert  a  string  to  a  quark. 

Convert  a  key  string  to  a  quark  list. 

Allocate  a  new  quark. 

Rotate  the  cut  buffers. 

Rotate  properties  in  the  properties  array. 

Save  a  data  value  corresponding  to  a  window  and 

context  type  (not  graphics  context). 

Select  the  event  types  to  be  sent  to  a  window. 

Send  an  event 

Disable  or  enable  access  control. 

Set  a  function  called  after  all  Xlib  functions. 

Set  the  arc  mode  in  a  graphics  context. 

Set  the  background  pixel  value  in  a  graphics  context. 

Set  the  XA_WM_CLASS  property  of  a  window. 

Set  clip_mask  pixmap  in  a  graphics  context. 

Set  the  clip  origin  in  a  graphics  context. 

Change  clip_mask  in  a  graphics  context  to  the 

list  of  rectangles. 

Change  the  close  down  mode  of  a  client. 

Set  the  XA_WM_COMMAND  atom  (command  line  arguments). 

Set  dash_of  f  set  and  dashes  (for  lines)  in  a  graphics  context. 

Set  a  nonfatal  error  event  handler. 

Set  the  fill  rule  in  a  graphics  context. 

Set  the  fill  style  in  a  graphics  context. 

Set  the  current  font  in  a  graphics  context. 

Set  the  font  search  path. 

Set  the  foreground  pixel  value  in  a  graphics  context. 

Set  the  bitwise  logical  operation  in  a  graphics  context. 

Set  graphics_exposures  in  a  graphics  context. 

Set  the  name  to  be  displayed  in  a  window's  icon. 

Set  the  value  of  the  XA_WM_ICON_SIZE  property. 

Set  the  keyboard  focus  window. 

Handle  fatal  I/O  errors. 

Set  the  line  drawing  components  in  a  graphics  context. 

Set  keycodes  to  be  used  as  modifiers  (Shift,  Control, 

etc.). 

Set  the  size  hints  property  of  a  window  in  normal  state 

(not  zoomed  or  iconified). 

Set  the  plane  mask  in  a  graphics  context. 

Set  the  pointer  button  mapping. 


570 


Xlib  Reference  Manual 


Table  A-1.  Alphabetical  Listing  of  Routines  (continued) 


Routine 


Description 


XSetRegion 
XSetRGBColormaps 

XSetScreenSaver 

XSet Select ionOwner 

XSetSizeHints 

XSetStandardColormap 

XSetStandardProperties 

XSetState 

XSetStipple 

XSetSubwindowMode 

XSetTextProperty 

XSetTile 

XSetTransientForHint 

XSetTSOrigin 

XSetWindowBackground 

XSetWindowBackground- 

Pixmap 
XSetWindowBorder 

XSetWindowBorderP  ixmap 

XSetWindowBorderWidth 

XSetWindowColormap 

XSetWMClientMachine 

XSetWMColormapWindows 

XSetWMHints 

XSetWMIconName 

XSetWMName 

XSetWMNormalHints 

XSetWMProperties 

XSetWMProtocols 
XSetWMSizeHints 

XSetZoomHints 
XShrinkRegion 
XStoreBuffer 


Set  clip_mask  of  the  graphics  context  to 

the  specified  region. 

Write  standard  colormap  property.  Replaces 

XSetStandardColormap. 

Set  the  parameters  of  the  screen  saver. 

Set  the  owner  of  a  selection. 

Set  the  value  of  any  property  of  type  XA_WM_S  I  z  E_H  I  N  T  s . 

Change  the  standard  colormap  property. 

Set  the  minimum  set  of  properties  for  the  window  manager. 

Set  the  foreground,  background,  logical  function,  and 

plane  mask  in  a  graphics  context. 

Set  the  stipple  in  a  graphics  context. 

Set  the  subwindow  mode  in  a  graphics  context. 

Write  a  TEXT  property  using  XTextProperty  structure. 

Set  the  fill  tile  in  a  graphics  context. 

Set  the  XA_WM_TRANSIENT_FOR  property 

of  a  window. 

Set  the  tile/stipple  origin  in  a  graphics  context. 

Set  the  background  pixel  attribute  of  a  window. 

Change  the  background  tile  attribute  of 

a  window. 

Change  a  window  border  attribute  to  the  specified 

pixel  value  and  repaint  the  border. 

Change  a  window  border  tile  attribute  and  repaint 

the  border. 

Change  the  border  width  of  a  window. 

Set  the  colormap  for  a  specified  window. 

Write  WM_CLIENT_MACHINE  property. 

Write  WM_COLORMAP_WINDOWS  property. 

Set  a  window  manager  hints  property. 

Write  XA_WM_ICON_NAME  property.  Replaces 

XSetlconName. 

Write  XA_WM_NAME  property.  Replaces 

XStoreName. 

Write  XA_WM_NORMAL_HINTS  property. 

Replaces  XSetNormalHints. 

Write  all  standard  properties.  Replaces 

XSetStandardProperties. 

Write  WM_PROTOCOLS  property. 

Write  XA_WM_SIZE_HINTS  property.  Replaces 

XSetSizeHints. 

Set  the  size  hints  property  of  a  zoomed  window. 

Reduce  or  expand  the  size  of  a  region. 

Store  data  in  a  cut  buffer. 


Function  Group  Summary 
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Table  A-1.  Alphabetical  Listing  of  Routines  (continued) 


Routine 


Description 


XStoreBytes 
XStoreColor 

XStoreColors 

XStoreName 

XStoreNamedColor 

XStringListToTextProperty 

XStringToKeysym 
XSublmage 
XSubtract Region 
XSync 

XSynchronize 

XTextExtents 

XTextExtentslG 

XTextWidth 

XTextWidthlG 

XTranslateCoordinates 

XUndef ineCursor 

XUngrabButton 

XUngrabKey 

XUngrabKeyboard 

XUngrabPointer 

XUngrabServer 

XUninstallColormap 

XUnionRectWithRegion 

XUnionRegion 

XUniqueContext 

XUnloadFont 

XUnmapSubwindows 

XUnmapWindow 

XWarpPointer 

XWindowEvent 

XWMGeometry 

XWriteBitmapFile 
XXorRegion 


Store  data  in  cut  buffer  0. 

Set  or  change  a  read/write  entry  of  a  colormap  to  the  closest 

available  hardware  color. 

Set  or  change  read/write  colorcells  to  the  closest  available 

hardware  colors. 

Assign  a  name  to  a  window  for  the  window  manager. 

Allocate  a  read/write  colorcell  by  English  color  name. 

Convert  a  list  of  strings  to  an  XText Property 

structure. 

Convert  a  keysym  name  string  to  a  keysym. 

Create  a  subimage  from  part  of  an  image. 

Subtract  one  region  from  another. 

Rush  the  request  buffer  and  wait  for  all  events  and  errors 

to  be  processed  by  the  server. 

Enable  or  disable  synchronization  for  debugging. 

Get  string  and  font  metrics. 

Get  string  and  font  metrics  of  a  16-bit  character  string. 

Get  the  width  in  pixels  of  an  8-bit  character  string. 

Get  the  width  in  pixels  of  a  16-bit  character  string. 

Change  the  coordinate  system  from  one  window  to 

another. 

Disassociate  a  cursor  from  a  window. 

Release  a  button  from  grab. 

Release  a  key  from  grab. 

Release  the  keyboard  from  grab. 

Release  the  pointer  from  grab. 

Release  the  server  from  grab. 

Uninstall  a  colormap;  install  default  if  not 

already  installed. 

Add  a  rectangle  to  a  region. 

Compute  the  union  of  two  regions. 

Create  a  new  context  ID  (not  graphics  context). 

Unload  a  font 

Unmap  all  subwindows  of  a  given  window. 

Unmap  a  window. 

Move  the  pointer  to  another  point  on  the  screen. 

Remove  the  next  event  matching  mask  and  window. 

Calculate  window  geometry  given  user  geometry  string 

and  default  geometry. 

Write  a  bitmap  to  a  file. 

Calculate  the  difference  between  the  union  and  intersection 

of  two  regions. 
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B 
Error  Messages  and  Protocol  Requests 


This  appendix  contains  two  tables:  Table  B-l  describes  the  standard  error  codes  (the 
error_code  member  of  XErrorEvent)  and  what  causes  them,  and  Table  B-2  describes 
the  mapping  between  protocol  requests  and  Xlib  functions.  Each  reference  page  in  this  vol 
ume  describes  in  more  detail  the  errors  that  may  occur  because  of  that  Xlib  routine.  Volume 
One,  Chapter  3,  Basic  Window  Program,  describes  the  handling  of  errors  in  general. 

A  protocol  request  is  the  actual  network  message  that  is  sent  from  Xlib  to  the  server.  Many 
convenience  functions  are  provided  in  Xlib  to  make  programs  easier  to  write  and  more  read 
able.  When  any  one  of  several  convenience  routines  is  called  it  will  be  translated  into  one 
type  of  protocol  request.  For  example,  XMoveWindow  and  XResizeWindow  are  conve 
nience  routines  for  the  more  general  XConf  igureWindow.  Both  of  these  Xlib  routines 
use  the  protocol  request  Configure  Window.  The  protocol  request  that  causes  an  error,  along 
with  other  information  about  the  error  is  printed  to  the  standard  error  output  by  the  default 
error  handlers.  In  order  to  find  out  where  in  your  code  the  error  occurred,  you  will  need  to 
know  what  Xlib  function  to  look  for.  Use  Table  B-2  to  find  this  function. 

Xlib  functions  that  do  not  appear  in  Table  B-2  do  not  generate  protocol  requests.  They  per 
form  their  function  without  affecting  the  display  and  without  requiring  information  from  the 
server.  If  errors  can  occur  in  them,  the  errors  are  reported  in  the  returned  value. 

Table  B-1.  Error  Messages 


Error  Codes: 


Possible  Cause 


BadAccess 


BadAlloc 
BadAtom 


Specifies  that  the  client  attempted  to  grab  a  key/button  combination 
that  is  already  grabbed  by  another  client;  free  a  colormap  entry  that 
is  not  allocated  by  the  client;  store  into  a  read-only  colormap  entry; 
modify  the  access  control  list  from  other  than  the  local  (or  otherwise 
authorized)  host;  or  select  an  event  type  that  only  one  client  can 
select  at  a  time,  when  another  client  has  already  selected  it. 

Specifies  that  the  server  failed  to  allocate  the  requested  resource. 

Specifies  that  a  value  for  an  Atom  argument  does  not  name  a  defined 
Atom. 
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Table  B-1.  Error  Messages  (continued) 


Error  Codes: 


Possible  Cause 


BadColor 

BadCursor 

BadDrawable 

BadFont 

BadGC 

BadlDChoice 


Badlmplement- 
ation 


BadLength 
BadMatch 

BadName 
BadPixmap 

BadRequest 
BadValue 

BadWindow 


Specifies  that  a  value  for  a  Colormap  argument  does  not  name  a 
defined  Colormap. 

Specifies  that  a  value  for  a  Cursor  argument  does  not  name  a 
defined  Cursor. 

Specifies  that  a  value  for  a  Drawable  argument  does  not  name  a 
defined  Window  or  Pixmap. 

Specifies  that  a  value  for  a  Font  or  GContext  argument  does  not 
name  a  defined  Font. 

Specifies  that  a  value  for  a  GContext  argument  does  not  name  a 
defined  GContext. 

Specifies  that  the  value  chosen  for  a  resource  identifier  either  is  not 
included  in  the  range  assigned  to  the  client  or  is  already  in  use. 

Specifies  that  the  server  does  not  implement  some  aspect  of  the 
request  A  server  that  generates  this  error  for  a  core  request  is  defi 
cient.  Clients  should  be  prepared  to  receive  such  errors  and  either 
handle  or  discard  them. 

Specifies  that  the  length  of  a  request  is  shorter  or  longer  than  that 
required  to  minimally  contain  the  arguments.  This  usually  indicates 
an  internal  Xlib  error. 

Specifies  that  an  inputOnly  window  is  used  as  a  Drawable. 

Some  argument  (or  pair  of  arguments)  has  the  correct  type  and  range 
but  fails  to  "match"  in  some  other  way  required  by  the  request 

Specifies  that  a  font  or  color  of  the  specified  name  does  not  exist. 

Specifies  that  a  value  for  a  Pixmap  argument  does  not  name  a 
defined  Pixmap. 

Specifies  that  the  major  or  minor  opcode  does  not  specify  a  valid 
request 

Specifies  that  some  numeric  value  falls  outside  the  range  of  values 
accepted  by  the  request  Unless  a  specific  range  is  specified  for  an 
argument,  the  full  range  defined  by  the  argument's  type  is  accepted. 
Any  argument  defined  as  a  set  of  alternatives  can  generate  this  error. 

Specifies  that  a  value  for  a  window  argument  does  not  name  a 
defined  window. 


The  BadAtom,  BadColor,  BadCursor,  BadDrawable,  BadFont,  BadGC,  Bad 
Pixmap,  and  BadWindow  errors  are  also  used  when  the  argument  type  should  be  among  a 
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set  of  fixed  alternatives  (for  example,  a  window  ID,  PointerRoot,  or  None)  and  some 
other  constant  or  variable  is  used. 

Table  B-2.  Xlib  Functions  and  Protocol  Requests 


Protocol  Request 


AllocColor 

AllocColorCells 

AllocColorPlanes 

AllocNamedColor 

AllowEvents 

Bell 

ChangeActivePointerGrab 

ChangeGC 


ChangeHosts 

ChangeKeyboardControl 

ChangeKeyboardMapping 

ChangePointerControl 

ChangeProperty 


Xlib  Function 


XAllocColor 

XAllocColorCells 

XAllocColorPlanes 

XAllocNamedColor 

XAllowEvents 

XBell 

XChange Act ivePointer Grab 

XChangeGC 

XSetArcMode 

XSet Background 

XSetClipMask 

XSetClipOrigin 

XSetFillRule 

XSetFillStyle 

XSetFont 

XSet Foreground 

XSetFunction 

XSetGraphicsExposures 

XSetLineAttributes 

XSetPlaneMask 

XSetState 

XSetStipple 

XSetSubwindowMode 

XSetTile 

XSetTSOrigin 

XAddHost 
XAddHosts 
XRemoveHost 
XRemoveHosts 

XAutoRepeatOff 

XAutoRepeatOn 

XChangeKeyboardControl 

XChangeKeyboardMapping 
XChangePointerControl 

XChangeProperty 

XSetCommand 

XSetlconName 

XSetlconSizes 

XSetNormalHints 
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Table  B-2.  Xlib  Functions  and  Protocol  Requests  (continued) 


Protocol  Request 


Xlib  Function 


ChangeSaveSet 


Change  Window  Attributes 


CirculateWindow 

Clear  Area 
CloseFont 
Configure  Window 


ConvertSelection 
Copy  Area 

CopyColormapAndFree 
CopyGC 
CopyPlane 


XSetWMProperties 

XSetSizeHints 

XSetStandardProperties 

XSetWMHints 

XSetZoomHints 

XStoreBuffer 

XStoreBytes 

XStoreName 

XAddToSaveSet 

XChangeSaveSet 

XRemoveFromSaveSet 

XChangeWindowAttributes 

XDefineCursor 

XSelectlnput 

XSetWindowBackground 

XSetWindowBackgroundPixmap 

XSetWindowBorder 

XSetWindowBorderPixmap 

XSetWindowColormap 

XUndef ineCursor 

XCirculateSubwindows 

XCirculateSubwindowsDown 

XCirculateSubwindowsUp 

XClearArea 
XClearWindow 

XFreeFont 
XUnloadFont 

XConfigureWindow 

XLowerWindow 

XMapRaised 

XMoveResize Window 

XMoveWindow 

XRaiseWindow 

XReconfigureWMWindow 

XResizeWindow 

XRestackWindows 

XSetWindowBorderWidth 

XCon vert Select ion 

XCopyArea 

XCopyColormapAndFree 

XCopyGC 

XCopyPlane 
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Table  B-2.  Xlib  Functions  and  Protocol  Requests  (continued) 


Protocol  Request 


Xlib  Function 


CreateColormap 

CreateCursor 

CreateGC 

CreateGlyphCursor 

CreatePixmap 
Create  Window 

DeleteProperty 

DestroySubwindows 

DestroyWindow 

FillPoly 

ForceScreenSaver 

FreeColormap 

FreeColors 

FreeCursor 

FreeGC 

FreePixmap 

GetAtomName 

GetFontPath 

GetGeometry 

Getlmage 
GetlnputFocus 

GetKeyboardControl 

GetKeyboardMapping 

GetModifierMapping 

GetMotionEvents 

GetPointerControl 

GetPointerMapping 


XCreateColormap 
XCreatePixmapCursor 

XCreateGC 
XOpenDisplay 

XCr eat eFont Cursor 
XCreateGlyphCursor 

XCreatePixmap 

XCreateSimpleWindow 
XCreateWindow 

XDeleteProperty 
XDestroySubwindows 
XDestroyWindow 
XFillPolygon 

XActi vat e ScreenSaver 
XForceScreenSaver 
XRe set ScreenSaver 

XFreeColormap 

XFreeColors 

XFreeCursor 

XFreeGC 

XFreePixmap 

XGetAtomName 

XGetFontPath 

XGetGeometry 
XGetWindowAttributes 

XGet Image 

XGetlnputFocus 
XSync 

XGetKeyboardControl 

XGetKeyboardMapping 

XGetModifierMapping 

XGetMotionEvents 

XGetPointerControl 

XGetPonterMapping 
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Table  B-2.  Xlib  Functions  and  Protocol  Requests  (continued) 


Protocol  Request 


Xlib  Function 


GetProperty 


GetScreenSaver 

GetSelectionOwner 

GetWindow  Attributes 

GrabButton 

GrabKey 

GrabKeyboard 

GrabPointer 

GrabServer 

ImageTextS 

ImageTextl6 

InstallColormap 

InternAtom 

KillClient 

ListExtensions 

ListFonts 

ListFontsWithlnfo 

ListHosts 

LisanstaUedColormaps 

ListProperties 

LookupColor 

MapS  ub  windows 
MapWindow 

NoOperation 


XFetchBytes 

XFetchName 

XGetlconSizes 

XGet IconName 

XGetNormalHints 

XGetSizeHints 

XGe tWindowP roperty 

XGetWMProperties 

XGetWMHints 

XGetZoomHints 

XGetScreenSaver 

XGet Select ionOwner 

XGetWindowAttributes 

XGrabButton 

XGrabKey 

XGrabKeyboard 

XGrabPointer 

XGrabServer 

XDrawImageString 

XDrawImageStringlG 

XInstallColormap 

XInternAtom 

XKillClient 

XList Ext ens ions 

XListFonts 

XListFontsWithlnfo 

XListHosts 

XList InstalledColormaps 

XListProperties 

XLookupColor 
XParseColor 

XMapSubwindows 

XMapRaised 
XMapWindow 

XNoOp 
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Table  B-2.  Xlib  Functions  and  Protocol  Requests  (continued) 


Protocol  Request 


Xlib  Function 


OpenFont 
PolyArc 
PolyFillArc 
PolyFillRectangle 

PolyLine 
PolyPoint 

PolyRectangle 
Poly  Segment 
PolyText8 
PolyTextl6 

Putlmage 
QueryBestSize 

QueryColors 
QueryExtension 

QueryFont 
QueryKeymap 
QueryPointer 
QueryTextExtents 

Query  Tree 
RecolorCursor 
ReparentWindow 
RotateProperties 


XLoadFont 
XLoadQueryFont 

XDrawArc 
XDrawArcs 

XFillArc 
XFillArcs 

XFillRectangle 
XFillRectangles 

XDrawLines 

XDrawPoint 
XDrawPoints 

XDrawRect angle 
XDrawRect angles 

XDrawLine 
XDrawSegments 

XDrawString 
XDrawText 

XDrawStringl6 
XDrawText 16 

XPut Image 

XQueryBest Cursor 
XQueryBestSize 
XQueryBest Stipple 
XQueryBestTile 

XQueryColor 
XQueryColors 

XInitExtension 
XQueryExtension 

XLoadQueryFont 
XQueryKeymap 
XQueryPo inter 

XQueryText Extents 
XQueryTextExtentsl6 

XQueryTree 
XRecolor Cursor 
XReparentWindow 
XRotateBuffers 
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Table  B-2.  Xlib  Functions  and  Protocol  Requests  (continued) 


Protocol  Request 


Xlib  Function 


SendEvent 
SetAccessControl 

SetClipRectangles 

SetCloseDownMode 

SetDashes 

SetFontPath 

SetlnputFocus 

SetModifierMapping 

SetPointerMapping 

SetScreenSaver 

SetSelectionOwner 

StoreColors 

StoreNamedColor 

TranslateCoords 

UngrabButton 

UngrabKey 

UngrabKeyboard 

UngrabPointer 

UngrabServer 

UninstallColormap 

UnmapS  ubwindows 

UnmapWindow 

WarpPointer 


XRotateWindowProperties 
XSendEvent 

XDisableAccessControl 

XEnableAccessControl 

XSetAccessControl 

XSetClipRect angles 

XSetCloseDownMode 

XSetDashes 

XSetFontPath 

XSetlnputFocus 

XSetModifierMapping 

XSetPointerMapping 

XSetScreenSaver 

XSet Select ionOwner 

XStoreColor 
XStoreColors 

XStoreNamedColor 

XTranslateCoordinates 

XUngrabButton 

XUngrabKey 

XUngrabKeyboard 

XUngrabPointer 

XUngrabServer 

XUninstallColormap 

XUnmapSubWindows 

XUnmapWindow 

XWarpPointer 
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c 

Macros 


Once  you  have  successfully  connected  your  application  to  an  X  server,  you  can  obtain  data 
from  the  Display  structure  associated  with  that  display.  The  Xlib  interface  provides  a 
number  of  useful  C  language  macros  and  corresponding  functions  for  other  language  bind 
ings  which  return  data  from  the  Display  structure. 

The  function  versions  of  these  macros  have  the  same  names  as  the  macros  except  that  the 
function  forms  begin  with  the  letter  "X."  They  use  the  same  arguments.  Using  the  macro 
versions  is  slightly  more  efficient  in  C  because  it  eliminates  function  call  overhead. 

In  R3  and  R4,  a  few  new  functions  were  added  that  access  members  of  the  Display  struc 
ture.  These  are  XDisplayMotionBufferSize,  XResourceManagerString, 
XDisplayKeycodes,  and  XMaxRequestSize  in  R3  and  XScreenNumber- 
OfScreen,  XListDepths,  and  XListPixmapFormats  in  R4.  Also,  XVisual- 
iDFromVisual  was  added  in  R3  to  extract  the  resource  ID  from  a  visual  structure. 
XDisplayMotionBufferSize,  XResourceManagerString,  XMaxRequest 
Size,  XScreenNumberOf  Screen,  and  XVisuallDFromVisual  are  simple  enough 
to  have  macro  versions,  but  these  were  not  provided.  Nevertheless,  we  have  chosen  to  cover 
them  in  this  macro  appendix  instead  of  devoting  a  reference  page  to  each.  XDisplay 
Keycodes,  XListDepths,  and  XListPixmapFormats  are  more  complicated  and 
therefore  have  their  own  reference  pages;  they  are  not  covered  here. 

For  the  purposes  of  this  appendix,  the  macros  are  divided  into  four  categories:  Display  mac 
ros,  Image  Format  macros,  Keysym  Classification  macros,  and  Resource  Manager  macros. 
The  macros  are  listed  alphabetically  within  each  category. 

Note  that  some  macros  take  as  arguments  an  integer  screen  (scr_num)  while  others  take  a 
pointer  to  a  Screen  structure  (scr_ptr).  scr_num  is  returned  by  the  Default- 
Screen  macro  and  scr_ptr  is  returned  by  the  Default  ScreenOf  Display  macro. 
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C.1   Display  Macros 


AllPlanes 


BlackPixel(di splay,  scr_num) 


BlackPixelOf Screen (scr_ptr) 


CellsOf Screen (scr_ptr) 


Connect  ionNumber(disp_Z  ay) 


Return  a  value  with  all  bits  set  suitable  for  use  as 
a  plane  mask  argument 

Return  the  black  pixel  value  in  the  default  color- 
map  that  is  created  by  XOpenDisplay. 

Return  the  black  pixel  value  in  the  default  color- 
map  of  the  specified  screen. 

Return  the  number  of  colormap  cells  in  the 
default  colormap  of  the  specified  screen. 


Return  a  connection  number  for  the  specified 
display.  On  a  UNIX  system,  this  is  the  file 
descriptor  of  the  connection. 

DefaultColormap(dispJay,scr_/ium)    Return  the  default  colormap  for  the  specified 

screen.  Most  routine  allocations  of  color  should 
be  made  out  of  this  colormap. 

DefauitCoiormapOf Screen (scr_ptr)  Return  the  default  colormap  of  the  specified 

screen. 


DefaultDepth(dJsplay,scr_/iu/n) 


DefaultDepthOf Screen (scr_ptr) 
DefaultGC(dispJay,scr_/5u/n) 

DefaultGCOfScreen(scr  ptr) 
DefaultRootWindow(dispIay) 

DefaultScreen(dispJay) 


Return  the  depth  (number  of  planes)  of  the  root 
window  for  the  specified  screen.  Other  depths 
may  also  be  supported  on  this  screen.  See  Vol 
ume  One,  Chapter  7,  Color,  or  the  reference 
pages  for  XMatchVisuallnfo  and  XGet- 
visuallnfo  to  find  out  how  to  determine 
what  depths  are  available. 

Return  the  default  depth  of  the  specified  screen. 

Return  the  default  graphics  context  for  the  speci 
fied  screen. 

Return  the  default  graphics  context  (GC)  of  the 
specified  screen. 

Return  the  ID  of  the  root  window  on  the  default 
screen.  Most  applications  should  use  Root- 
window  instead  so  that  screen  selection  is  sup 
ported. 

Return  the  integer  that  was  specified  in  the  last 
segment  of  the  string  passed  to  XOpen 
Display  or  from  the  DISPLAY  environment 
variable  if  NULL  was  used.  For  example,  if  the 
DISPLAY  environment  were  Ogre :  0  . 1,  then 
Def  aultScreen  would  return  1. 
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DefaultScreenOfDisplay(display)     Return  the  default  screen  of  the  specified  dis 
play. 


DefaultVisual(display,scr_/7um) 

DefaultVisualOf Screen (scr_ptr) 
DisplayCells  (display,  scr_num) 


DisplayHeight(display,scr_r3um) 


DisplayHeightMM(display,scr_/iu/n) 


DisplayOf Screen (scr_ptr) 


Display?  lanes  (displ  ay,  scr_n  urn) 


Display String (display) 


DisplayWidth(d-isp_Zay,scr  nu/n) 


DisplayWidthMM(dispIay,scr  num) 


DoesBackingStore(scr_ptr) 


DoesSaveUnders (scr_ptr) 


Return  a  pointer  to  the  default  visual  structure 
for  the  specified  screen. 

Return  the  default  visual  of  the  specified  screen. 

Return  the  maximum  possible  number  of  color- 
map  cells  on  the  specified  screen.  This  macro  is 
misnamed:  it  should  have  been  Screen- 
Cells. 

Return  the  height  in  pixels  of  the  screen.  This 
macro  is  misnamed:  it  should  have  been 
ScreenHeight. 

Return  the  height  in  millimeters  of  the  specified 
screen.  This  macro  is  misnamed:  it  should  have 
been  ScreenHeightMM. 

Return  the  display  associated  with  the  specified 
screen. 

Return  the  number  of  planes  on  the  specified 
screen.  This  macro  is  misnamed:  it  should  have 
been  ScreenPlanes. 

Return  the  string  that  was  passed  to  XOpen- 
Di splay  when  the  current  display  was  opened 
(or,  if  that  was  NULL,  the  value  of  the  DISPLAY 
environment  variable).  This  macro  is  useful  in 
applications  which  invoke  the  fork  system  call 
and  want  to  open  a  new  connection  to  the  same 
display  from  the  child  process. 

Return  the  width  in  pixels  of  the  screen.  This 
macro  is  misnamed:  it  should  have  been 
ScreenWidth. 

Return  the  width  in  millimeters  of  the  specified 
screen.  This  macro  is  misnamed:  it  should  have 
been  ScreenWidthMM. 

Return  a  value  indicating  whether  the  screen 
supports  backing  stores.  Values  are  When- 
Mapped,  NotUsef  ul,  or  Always.  See  Vol 
ume  One,  Section  4.3.5  for  a  discussion  of  the 
backing  store. 

Return  a  Boolean  value  indicating  whether  the 
screen  supports  save  unders.  If  True,  the 
screen  supports  save  unders.  If  False,  the 
screen  does  not  support  save  unders.  See 
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dpyno( display) 

EventMaskOf Screen (scr_ptr) 
He ightOf Screen (scr_ptr) 
HeightMMOf Screen (scr_ptr) 
Keyboard (display) 


LastKnownRequestProcessed 
(display) 


MaxCmapsOf Screen (scr_ptr) 
MinCmapsOf Screen(scr  ptr) 
Next Request (display) 

PlanesOf Screen (scr_ptr) 
ProtocolRe vision (display) 
ProtocolVersion(display) 

QLength(display) 
RootWindow(display,scr  num) 


Volume  One,  Section  4.3.6  for  a  discussion  of 
the  save  under. 

Return  the  file  descriptor  of  the  connected  dis 
play.  On  a  UNIX  system,  you  can  then  pass  this 
returned  file  descriptor  to  the  select(3)  system 
call  when  your  application  program  is  driving 
more  than  one  display  at  a  time. 

Return  the  initial  event  mask  for  the  root  win 
dow  of  the  specified  screen. 

Return  the  height  in  pixels  of  the  specified 
screen. 

Return  the  height  in  millimeters  of  the  specified 
screen. 

Return  the  device  ID  for  the  main  keyboard  con 
nected  to  the  display. 

Return  the  serial  ID  of  the  last  known  protocol 
request  to  have  been  issued.  This  can  be  useful 
in  processing  errors,  since  the  serial  number  of 
failing  requests  are  provided  in  the  XError- 
Event  structure. 

Return  the  maximum  number  of  installed  (hard 
ware)  colormaps  supported  by  the  specified 
screen. 

Return  the  minimum  number  of  installed  (hard 
ware)  colormaps  supported  by  the  specified 
screen. 

Return  the  serial  ID  of  the  next  protocol  request 
to  be  issued.  This  can  be  useful  in  processing 
errors,  since  the  serial  number  of  failing  requests 
are  provided  in  the  XErrorEvent  structure. 

Return  the  number  of  planes  in  the  specified 
screen. 

Return  the  minor  protocol  revision  number  of 
the  X  server. 

Return  the  version  number  of  the  X  protocol 
associated  with  the  connected  display.  This  is 
currently  11. 

Return  the  number  of  events  that  can  be  queued 
by  the  specified  display. 

Return  the  ID  of  the  root  window.  This  macro  is 
necessary  for  routines  that  reference  the  root 
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RootWindowOf Screen (scr_ptr) 
ScreenCount( display) 
ScreenOf  Display  (disp_Zay,scr_/iim?) 
ServerVendor( display) 

VendorRe lease (display) 
WhitePixel(display,scr_/]U/n) 
WhitePixelOf Screen (scr_ptr) 

WidthOfScreen(scr_ptr) 
WidthMMOfScreen(scr_ptr) 

XDisplayMotionBufferSize (display) 

XMaxRequestSize(dispIay) 

XScreenNumberOf Screen (scr_ptr) 
XVisualIDFromVisual( visual) 


window  or  create  a  top-level  window  for  an 
application. 

Return  the  ID  of  the  root  window  of  the  speci 
fied  screen. 

Return  the  number  of  available  screens  on  a 
specified  display. 

Return  the  specified  screen  of  the  specified  dis 
play. 

Return  a  pointer  to  a  null  terminated  string  giv 
ing  some  identification  of  the  owner  of  the  X 
server  implementation. 

Return  a  number  related  to  the  release  of  the  X 
server  by  the  vendor. 

Return  the  white  pixel  value  in  the  default  color- 
map  that  is  created  by  XOpenDi splay. 

Return  the  white  pixel  value  in  the  default  color- 
map  of  the  specified  screen. 

Return  the  width  of  the  specified  screen. 

Return  the  width  of  the  specified  screen  in  milli 
meters. 


Return  an  unsigned  long  value  containing 
the  size  of  the  motion  buffer  on  the  server.  If 
this  function  returns  zero,  the  server  has  no 
motion  history  buffer. 

Return  a  long  value  containing  the  maximum 
size  of  a  protocol  request  for  the  specified  server, 
in  units  of  four  bytes. 

Return  the  integer  screen  number  corresponding 
to  the  specified  pointer  to  a  Screen  structure. 

Returns  the  ID  of  the  server  resource  associated 
with  a  visual  structure.  This  is  useful  when  stor 
ing  standard  colormap  properties. 
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C.2  Image  Format  Macros 

BitmapBitOrder(display)  Within  each  BitmapUnit,  the  leftmost  bit  in  the  bit 
map  as  displayed  on  the  screen  is  either  the  least  or  the 
most  significant  bit  in  the  unit.  Returns  LSBFirst  or 
MSBFirst. 

BitmapPad(display)  Each  scan  line  must  be  padded  to  a  multiple  of  bits  speci 

fied  by  the  value  returned  by  this  macro. 

BitmapUnit  (display)  Returns  the  size  of  a  bitmap's  unit.  The  scan  line  is  quan 

tized  (calculated)  in  multiples  of  this  value. 

imageByteOrder(dispiay)        Returns  the  byte  order  for  images  required  by  the  server 

for  each  scan  line  unit  in  XY  format  (bitmap)  or  for  each 
pixel  value  in  Z  format.  Values  are  LSBFirst  or 
MSBFirst. 


C.3  Keysym  Classification  Macros 

You  may  want  to  test  if  a  keysym  of  the  defined  set  (XK_MISCELLANY)  is,  for  example,  on 
the  key  pad  or  the  function  keys.  You  can  use  the  keysym  macros  to  perform  the  following 
tests: 

I  sCursorKey  (keysym)  Return  True  if  the  keysym  represents  a  cursor  key. 

isFunctionKeyUeysym)  Return  True  if  the  keysym  represents  a  function  key. 

isKeypadKeyUeysym)  Return  True  if  the  keysym  represents  a  key  pad. 

I sMiscFunctionKey( keysym)    Return  True  if  the  keysym  represents  a  miscellaneous 

function  key. 

isModif  ierKey  (keysym)  Return  True  if  the  keysym  represents  a  modifier  key. 

i  sPFKey  (keysym)  Return  True  if  the  keysym  represents  a  PF  key. 


C.4  Resource  Manager  Macros 

These  macros  convert  from  strings  to  quarks  and  quarks  to  strings.  They  are  used  by  the 
resource  manager.  Note  that  they  do  not  follow  the  normal  naming  conventions  for  macros, 
since  they  begin  with  an  X. 

XrmStringToName(stri/ig)  Convert  String  to  XrmName.    Same  as  XString- 

ToQuark. 

XrmStringToClass(string)          Convert  String  to  XrmClass.    Same  as  XString- 

ToQuark. 
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XrmStringToRepresentation      Convert  String  to  XrmRepresentation.    Same  as 


(string) 
XrmNameToString(/ja/ne) 

XrmClassToString(class) 


XStringToQuark. 

Convert  XrmName  to  string.  Same  as  XrmQuark- 
ToString. 

Convert  XrmClass  to  string.  Same  as  XrmQuark- 
ToString. 

XrmRepresentationToString      Convert  XrmRepresentation  to  String.    Same  as 
(type)  XrmQuarkToString. 

XResourceManagerString( display) 

Return  a  pointer  to  the  resource  database  string  stored 
in  the  Display  structure.  This  string  is  read  from  the 
RESOURCE_MANAGER  property  on  the  root  window; 
this  property  is  normally  set  by  the  xrdb  client. 
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D 

The  Color  Database 


The  color  database  translates  color  name  strings  into  RGB  values.  It  is  used  by  XParse- 
Color,  XLookupColor,  and  xstoreNamedColor.  These  routines  make  it  easier  to 
allow  the  user  to  specify  color  names.  Use  of  these  names  for  routine  color  allocation  of 
read-only  colorcells  is  encouraged  since  this  increases  the  chance  of  sharing  colorcells  and 
thereby  makes  the  colormap  go  further  before  running  out  of  colorcells.  The  location  in  the 
file  system  of  the  text  version  of  the  color  database  is  an  implementation  detail,  but  by 
default  on  a  UNIX  system  it  is  lusrlliblXlllrgb.txt. 

It  should  be  noted  that  while  a  sample  color  database  is  provided  with  the  standard  XI 1  dis 
tribution,  it  is  not  specified  as  an  X  Consortium  standard  and  is  not  part  of  the  X  Protocol  or 
Xlib.  Therefore,  it  is  permissible  for  server  vendors  to  change  the  color  names,  although  they 
will  probably  only  add  color  names.  Furthermore,  hardware  vendors  can  change  the  RGB 
values  for  each  display  hardware  to  achieve  the  proper  "gamma  correction"  so  that  the  colors 
described  by  the  name  really  generate  that  color. 

The  RGB  values  in  the  R3  database  were  originally  tuned  for  the  DEC  VT240  display.  The 
color  that  appears  on  a  Sun  system  given  these  RGB  values  for  "pink,"  for  example,  looks 
more  like  light  burgundy.  In  R4  a  new  RGB  color  database  is  provided,  which  provides 
many  more  color  names  and  provides  values  that  generate  colors  that  match  their  names  on 
more  monitors. 

Each  color  name  in  the  database  may  be  used  in  the  form  shown  or  in  mixed  case,  with  initial 
capitals  and  all  spaces  eliminated.  Table  D-l  (see  next  page)  shows  the  R3  database,  and 
Table  D-2  shows  the  R4  database. 
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Table  D- 1.  The  R3  Color  Database ' 


English  Words 

Red 

Green 

Blue 

English  Words 

Red 

Green 

Blue 

English  Words 

Red 

Green 

Blue 

medium  aquamarine 

50 

204 

153 

aquamarine 

112 

219 

147 

English  Words 

Red 

Green 

Blue 

black 

0 

0 

0 

medium  blue 

50 

50 

204 

blue 

0 

0 

255 

medium  forest  green 

107 

142 

35 

blue  violet 

159 

95 

159 

medium  goldenrod 

234 

234 

173 

brown 

165 

42 

42 

medium  orchid 

147 

112 

219 

cadet  blue 

95 

159 

159 

medium  sea  green 

66 

111 

66 

coral 

255 

127 

0 

medium  slate  blue 

127 

0 

255 

cornflower  blue 

66 

66 

111 

medium  spring  green 

127 

255 

0 

cyan 

0 

255 

255 

medium  turquoise 

112 

219 

219 

dark  green 

47 

79 

47 

medium  violet  red 

219 

112 

147 

dark  olive  green 

79 

79 

47 

midnight  blue 

47 

47 

79 

dark  orchid 

153 

50 

204 

navy 

35 

35 

142 

dark  slate  blue 

107 

35 

142 

navy  blue 

35 

35 

142 

dark  slate  gray 

47 

79 

79 

orange 

204 

50 

50 

dark  slate  grey 

47 

79 

79 

orange  red 

255 

0 

127 

dark  turquoise 

112 

147 

219 

orchid 

219 

112 

219 

dim  gray 

84 

84 

84 

pale  green 

143 

188 

143 

dim  grey 

84 

84 

84 

pink 

188 

143 

143 

firebrick 

142 

35 

35 

plum 

234 

173 

234 

forest  green 

35 

142 

35 

purple 

176 

0 

255 

gold 

204 

127 

50 

red 

255 

0 

0 

goldenrod 

219 

219 

112 

salmon 

111 

66 

66 

gray 

192 

192 

192 

sea  green 

35 

142 

107 

green 

0 

255 

0 

sienna 

142 

107 

35 

green  yellow 

147 

219 

112 

sky  blue 

50 

153 

204 

grey 

192 

192 

192 

slate  blue 

0 

127 

255 

indian  red 

79 

47 

47 

spring  green 

0 

255 

127 

khaki 

159 

159 

95 

steel  blue 

35 

107 

142 

light  blue 

191 

216 

216 

tan 

219 

147 

112 

light  gray 

168 

168 

168 

thistle 

216 

191 

216 

light  grey 

168 

168 

168 

turquoise 

173 

234 

234 

light  steel  blue 

143 

143 

188 

violet 

79 

47 

79 

lime  green 

50 

204 

50 

violet  red 

204 

50 

153 

magenta 

255 

0 

255 

wheat 

216 

216 

191 

maroon 

142 

35 

107 

white 

252 

252 

252 

yellow 

255 

255 

0 

yellow  green 

153 

204 

50 

*Also  defined  are  the  color  names  "grayO"  through  "graylOO",  spelled  with  an  V  or  an  "a".  "grayO"  is  black  and 
"gray  100"  is  white. 
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Table  D-2.  The  R4  Color  Database 


English  Words 

Red 

Green 

Blue 

English  Words 

Red 

Green 

Blue 

snow 

255 

250 

250 

black 

0 

0 

0 

ghost  white 

248 

248 

255 

dark  slate  gray 

47 

79 

79 

GhostWhite 

248 

248 

255 

DarkSlateGray 

47 

79 

79 

white  smoke 

245 

245 

245 

dark  slate  grey 

47 

79 

79 

WhiteSmoke 

245 

245 

245 

DarkSlateGrey 

47 

79 

79 

gainsboro 

220 

220 

220 

dim  gray 

105 

105 

105 

floral  white 

255 

250 

240 

DimGray 

105 

105 

105 

Floral  White 

255 

250 

240 

dim  grey 

105 

105 

105 

old  lace 

253 

245 

230 

DimGrey 

105 

105 

105 

OldLace 

253 

245 

230 

slate  gray 

112 

128 

144 

linen 

250 

240 

230 

SlateGray 

112 

128 

144 

antique  white 

250 

235 

215 

slate  grey 

112 

128 

144 

AntiqueWhite 

250 

235 

215 

SlateGrey 

112 

128 

144 

papaya  whip 

255 

239 

213 

light  slate  gray 

119 

136 

153 

PapayaWhip 

255 

239 

213 

LightSlateGray 

119 

136 

153 

blanched  almond 

255 

235 

205 

light  slate  grey 

119 

136 

153 

BlanchedAlmond 

255 

235 

205 

LightSlateGrey 

119 

136 

153 

bisque 

255 

228 

196 

gray 

192 

192 

192 

peach  puff 

255 

218 

185 

grey 

192 

192 

192 

PeachPuff 

255 

218 

185 

light  grey 

211 

211 

211 

navajo  white 

255 

222 

173 

LightGrey 

211 

211 

211 

NavajoWhite 

255 

222 

173 

light  gray 

211 

211 

211 

moccasin 

255 

228 

181 

LightGray 

211 

211 

211 

cornsilk 

255 

248 

220 

midnight  blue 

25 

25 

112 

ivory 

255 

255 

240 

MidnightBlue 

25 

25 

112 

lemon  chiffon 

255 

250 

205 

navy 

0 

0 

128 

LemonChiffon 

255 

250 

205 

navy  blue 

0 

0 

128 

seasheU 

255 

245 

238 

NavyBlue 

0 

0 

128 

honeydew 

240 

255 

240 

cornflower  blue 

100 

149 

237 

mint  cream 

245 

255 

250 

ComflowerBlue 

100 

149 

237 

MintCream 

245 

255 

250 

dark  slate  blue 

72 

61 

139 

azure 

240 

255 

255 

DarkSlateBlue 

72 

61 

139 

alice  blue 

240 

248 

255 

slate  blue 

106 

90 

205 

AliceBlue 

240 

248 

255 

SlateBlue 

106 

90 

205 

lavender 

230 

230 

250 

medium  slate  blue 

123 

104 

238 

lavender  blush 

255 

240 

245 

MediumSlateBlue 

123 

104 

238 

LavenderBlush 

255 

240 

245 

light  slate  blue 

132 

112 

255 

misty  rose 

255 

228 

225 

LightSlateBlue 

132 

112 

255 

MistyRose 

255 

228 

225 

medium  blue 

0 

0 

205 

white 

255 

255 

255 

MediumBlue 

0 

0 

205 
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Table  D-2.  The  R4  Color  Database  (continued) 


English  Words 

Red 

Green 

Blue 

English  Words 

Red 

Green 

Blue 

royal  blue 

65 

105 

225 

sea  green 

46 

139 

87 

RoyalBlue 

65 

105 

225 

SeaGreen 

46 

139 

87 

blue 

0 

0 

255 

medium  sea  green 

60 

179 

113 

dodger  blue 

30 

144 

255 

MediumSeaGreen 

60 

179 

113 

DodgerBlue 

30 

144 

255 

light  sea  green 

32 

178 

170 

deep  sky  blue 

0 

191 

255 

LightSeaGreen 

32 

178 

170 

DeepSkyBlue 

0 

191 

255 

pale  green 

152 

251 

152 

sky  blue 

135 

206 

235 

PaleGreen 

152 

251 

152 

SkyBlue 

135 

206 

235 

spring  green 

0 

255 

127 

light  sky  blue 

135 

206 

250 

SpringGreen 

0 

255 

127 

LightSkyBlue 

135 

206 

250 

lawn  green 

124 

252 

0 

steel  blue 

70 

130 

180 

LawnGreen 

124 

252 

0 

SteelBlue 

70 

130 

180 

green 

0 

255 

0 

light  steel  blue 

176 

196 

222 

chartreuse 

127 

255 

0 

LightS  teelBlue 

176 

196 

222 

medium  spring  green 

0 

250 

154 

light  blue 

173 

216 

230 

MediumSpringGreen 

0 

250 

154 

LightBlue 

173 

216 

230 

green  yellow 

173 

255 

47 

powder  blue 

176 

224 

230 

GreenYellow 

173 

255 

47 

PowderBlue 

176 

224 

230 

lime  green 

50 

205 

50 

pale  turquoise 

175 

238 

238 

LimeGreen 

50 

205 

50 

PaleTurquoise 

175 

238 

238 

yellow  green 

154 

205 

50 

dark  turquoise 

0 

206 

209 

YellowGreen 

154 

205 

50 

DarkTurquoise 

0 

206 

209 

forest  green 

34 

139 

34 

medium  turquoise 

72 

209 

204 

ForestGreen 

34 

139 

34 

MediumTurquoise 

72 

209 

204 

olive  drab 

107 

142 

35 

turquoise 

64 

224 

208 

OliveDrab 

107 

142 

35 

cyan 

0 

255 

255 

dark  khaki 

189 

183 

107 

light  cyan 

224 

255 

255 

DarkKhaki 

189 

183 

107 

LightCyan 

224 

255 

255 

khaki 

240 

230 

140 

cadet  blue 

95 

158 

160 

pale  goldenrod 

238 

232 

170 

CadetBlue 

95 

158 

160 

PaleGoldenrod 

238 

232 

170 

medium  aquamarine 

102 

205 

170 

light  goldenrod  yellow 

250 

250 

210 

MediumAquamarine 

102 

205 

170 

LightGoldenrodYellow 

250 

250 

210 

aquamarine 

127 

255 

212 

light  yellow 

255 

255 

224 

dark  green 

0 

100 

0 

LightYellow 

255 

255 

224 

DarkGreen 

0 

100 

0 

yellow 

255 

255 

0 

dark  olive  green 

85 

107 

47 

gold 

255 

215 

0 

DarkOliveGreen 

85 

107 

47 

light  goldenrod 

238 

221 

130 

dark  sea  green 

143 

188 

143 

LightGoldenrod 

238 

221 

130 

DarkSeaGreen 

143 

188 

143 

goldenrod 

218 

165 

32 
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Table  D-2.  The  R4  Color  Database  (continued) 


English  Words 

Red 

Green 

Blue 

English  Words 

Red 

Green 

Blue 

dark  goldenrod 

184 

134 

11 

LightPink 

255 

182 

193 

DarkGoldenrod 

184 

134 

11 

pale  violet  red 

219 

112 

147 

rosy  brown 

188 

143 

143 

PaleVioletRed 

219 

112 

147 

RosyBrown 

188 

143 

143 

maroon 

176 

48 

96 

Indian  red 

205 

92 

92 

medium  violet  red 

199 

21 

133 

IndianRed 

205 

92 

92 

MediumVioletRed 

199 

21 

133 

saddle  brown 

139 

69 

19 

violet  red 

208 

32 

144 

SaddleBrown 

139 

69 

19 

VioletRed 

208 

32 

144 

sienna 

160 

82 

45 

magenta 

255 

0 

255 

peru 

205 

133 

63 

violet 

238 

130 

238 

burlywood 

222 

184 

135 

plum 

221 

160 

221 

beige 

245 

245 

220 

orchid 

218 

112 

214 

wheat 

245 

222 

179 

medium  orchid 

186 

85 

211 

sandy  brown 

244 

164 

96 

MediumOrchid 

186 

85 

211 

SandyBrown 

244 

164 

96 

dark  orchid 

153 

50 

204 

tan 

210 

180 

140 

DarkOrchid 

153 

50 

204 

chocolate 

210 

105 

30 

dark  violet 

148 

0 

211 

firebrick 

178 

34 

34 

DarkViolet 

148 

0 

211 

brown 

165 

42 

42 

blue  violet 

138 

43 

226 

dark  salmon 

233 

150 

122 

BlueViolet 

138 

43 

226 

DarkSalmon 

233 

150 

122 

purple 

160 

32 

240 

salmon 

250 

128 

114 

medium  purple 

147 

112 

219 

light  salmon 

255 

160 

122 

MediumPurple 

147 

112 

219 

LightS  almon 

255 

160 

122 

thistle 

216 

191 

216 

orange 

255 

165 

0 

snowl 

255 

250 

250 

dark  orange 

255 

140 

0 

snow2 

238 

233 

233 

DarkOrange 

255 

140 

0 

snow3 

205 

201 

201 

coral 

255 

127 

80 

snow4 

139 

137 

137 

light  coral 

240 

128 

128 

seashelll 

255 

245 

238 

LightCoral 

240 

128 

128 

seashel!2 

238 

229 

222 

tomato 

255 

99 

71 

seashelD 

205 

197 

191 

orange  red 

255 

69 

0 

seashel!4 

139 

134 

130 

OrangeRed 

255 

69 

0 

AntiqueWhitel 

255 

239 

219 

red 

255 

0 

0 

AntiqueWhite2 

238 

223 

204 

hot  pink 

255 

105 

180 

AntiqueWhite3 

205 

192 

176 

HotPink 

255 

105 

180 

AntiqueWhite4 

139 

131 

120 

deep  pink 

255 

20 

147 

bisque  1 

255 

228 

196 

DeepPink 

255 

20 

147 

bisque2 

238 

213 

183 

pink 

255 

192 

203 

bisque3 

205 

183 

158 

light  pink 

255 

182 

193 

bisque4 

139 

125 

107 
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Table  D-2.  The  R4  Color  Database  (continued) 


English  Words 

Red 

Green 

Blue 

English  Words 

Red 

Green 

Blue 

PeachPuffl 

255 

218 

185 

LightPink 

255 

182 

193 

PeachPuffZ 

238 

203 

173 

pale  violet  red 

219 

112 

147 

PeachPufO 

205 

175 

149 

PaleVioletRed 

219 

112 

147 

PeachPuff4 

139 

119 

101 

maroon 

176 

48 

96 

NavajoWhitel 

255 

222 

173 

medium  violet  red 

199 

21 

133 

NavajoWhite2 

238 

207 

161 

MediumVioletRed 

199 

21 

133 

NavajoWhiteS 

205 

179 

139 

violet  red 

208 

32 

144 

NavajoWhite4 

139 

121 

94 

VioletRed 

208 

32 

144 

LemonChiffonl 

255 

250 

205 

magenta 

255 

0 

255 

LemonChiffon2 

238 

233 

191 

violet 

238 

130 

238 

LemonChiffonS 

205 

201 

165 

plum 

221 

160 

221 

LemonChiffon4 

139 

137 

112 

orchid 

218 

112 

214 

cornsilkl 

255 

248 

220 

medium  orchid 

186 

85 

211 

cornsilk2 

238 

232 

205 

MediumOrchid 

186 

85 

211 

comsilk3 

205 

200 

177 

dark  orchid 

153 

50 

204 

cornsilk4 

139 

136 

120 

DarkOrchid 

153 

50 

204 

ivory  1 

255 

255 

240 

dark  violet 

148 

0 

211 

ivory2 

238 

238 

224 

DarkViolet 

148 

0 

211 

ivoryS 

205 

205 

193 

blue  violet 

138 

43 

226 

ivory4 

139 

139 

131 

BlueViolet 

138 

43 

226 

honeydewl 

240 

255 

240 

purple 

160 

32 

240 

honeydew2 

224 

238 

224 

medium  purple 

147 

112 

219 

honeydewS 

193 

205 

193 

MediumPurple 

147 

112 

219 

honeydew4 

131 

139 

131 

thistle 

216 

191 

216 

LavenderBlushl 

255 

240 

245 

snowl 

255 

250 

250 

LavenderBlush2 

238 

224 

229 

snow2 

238 

233 

233 

LavenderBlushS 

205 

193 

197 

snow3 

205 

201 

201 

LavenderBlush4 

139 

131 

134 

snow4 

139 

137 

137 

MistyRosel 

255 

228 

225 

seashelll 

255 

245 

238 

MistyRose2 

238 

213 

210 

seashel!2 

238 

229 

222 

MistyRose3 

205 

183 

181 

seashel!3 

205 

197 

191 

MistyRose4 

139 

125 

123 

seashel!4 

139 

134 

130 

azure  1 

240 

255 

255 

AntiqueWhitel 

255 

239 

219 

azure2 

224 

238 

238 

AntiqueWhite2 

238 

223 

204 

azureS 

193 

205 

205 

AntiqueWhite3 

205 

192 

176 

azure4 

131 

139 

139 

AntiqueWhite4 

139 

131 

120 

SlateBluel 

131 

111 

255 

bisque  1 

255 

228 

196 

SlateBlue2 

122 

103 

238 

bisque2 

238 

213 

183 

SlateBlueS 

105 

89 

205 

bisque3 

205 

183 

158 

SlateBlue4 

71 

60 

139 

bisque4 

139 

125 

107 
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Table  D-2.  The  R4  Color  Database  (continued) 


English  Words 

Red 

Green 

Blue 

English  Words 

Red 

Green 

Blue 

RoyalBluel 

72 

118 

255 

LightCyanl 

224 

255 

255 

RoyalBlue2 

67 

110 

238 

LightCyan2 

209 

238 

238 

RoyalBlueS 

58 

95 

205 

LightCyan3 

180 

205 

205 

RoyalBlue4 

39 

64 

139 

LightCyan4 

122 

139 

139 

bluel 

0 

0 

255 

PaleTurquoisel 

187 

255 

255 

blue2 

0 

0 

238 

PaleTurquoise2 

174 

238 

238 

blue3 

0 

0 

205 

PaleTurquoiseS 

150 

205 

205 

blue4 

0 

0 

139 

PaleTurquoise4 

102 

139 

139 

DodgerBluel 

30 

144 

255 

CadetBluel 

152 

245 

255 

DodgerBlue2 

28 

134 

238 

CadetBlue2 

142 

229 

238 

DodgerBlueS 

24 

116 

205 

CadetBlue3 

122 

197 

205 

DodgerBlue4 

16 

78 

139 

CadetBlue4 

83 

134 

139 

SteelBluel 

99 

184 

255 

turquoise  1 

0 

245 

255 

SteelBlue2 

92 

172 

238 

turquoise2 

0 

229 

238 

SteelBlueS 

79 

148 

205 

turquoise3 

0 

197 

205 

SteelBlue4 

54 

100 

139 

turquoise4 

0 

134 

139 

DeepSkyBluel 

0 

191 

255 

cyanl 

0 

255 

255 

DeepSkyBlue2 

0 

178 

238 

cyan2 

0 

238 

238 

DeepSkyBlue3 

0 

154 

205 

cyan3 

0 

205 

205 

DeepSkyBlue4 

0 

104 

139 

cyan4 

0 

139 

139 

SkyBluel 

135 

206 

255 

DarkSlateGrayl 

151 

255 

255 

SkyBlue2 

126 

192 

238 

DarkSlateGray2 

141 

238 

238 

SkyBlue3 

108 

166 

205 

DarkSlateGray3 

121 

205 

205 

SkyBlue4 

74 

112 

139 

DarkSlateGray4 

82 

139 

139 

LightSkyBluel 

176 

226 

255 

aquamarine  1 

127 

255 

212 

LightSkyBlue2 

164 

211 

238 

aquamarine2 

118 

238 

198 

LightSkyBlueS 

141 

182 

205 

aquamarines 

102 

205 

170 

LightSkyBlue4 

96 

123 

139 

aquamarine4 

69 

139 

116 

SlateGrayl 

198 

226 

255 

DarkSeaGreenl 

193 

255 

193 

SlateGray2 

185 

211 

238 

DarkSeaGreen2 

180 

238 

180 

SlateGrayS 

159 

182 

205 

DarkSeaGreenS 

155 

205 

155 

SlateGray4 

108 

123 

139 

DarkSeaGreen4 

105 

139 

105 

LightS  teelBluel 

202 

225 

255 

SeaGreenl 

84 

255 

159 

Lights  teelBlue2 

188 

210 

238 

ScaGreen2 

78 

238 

148 

LightSteelBlue3 

162 

181 

205 

SeaGreen3 

67 

205 

128 

LightS  teelBlue4 

110 

123 

139 

SeaGreen4 

46 

139 

87 

LightBluel 

191 

239 

255 

PaleGreenl 

154 

255 

154 

LightBlue2 

178 

223 

238 

PaleGreen2 

144 

238 

144 

LightBlueS 

154 

192 

205 

PaleGreen3 

124 

205 

124 

LightBlue4 

104 

131 

139 

PaleGreen4 

84 

139 

84 
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Table  D-2.  The  R4  Color  Database  (continued) 


English  Words 

Red 

Green 

Blue 

English  Words 

Red 

Green 

Blue 

SpringGreenl 

0 

255 

127 

goldenrodl 

255 

193 

37 

SpringGreen2 

0 

238 

118 

goldenrod2 

238 

180 

34" 

SpringGreenS 

0 

205 

102 

goldenrod3 

205 

155 

29 

SpringGreen4 

0 

139 

69 

goldenrod4 

139 

105 

20 

green  1 

0 

255 

0 

DarkGoldenrodl 

255 

185 

15 

green2 

0 

238 

0 

DarkGoldenrod2 

238 

173 

14 

green3 

0 

205 

0 

DarkGoldenrod3 

205 

149 

12 

green4 

0 

139 

0 

DarkGoldenrod4 

139 

101 

8 

chartreuse  1 

127 

255 

0 

RosyBrownl 

255 

193 

193 

chartreuse2 

118 

238 

0 

RosyBrown2 

238 

180 

180 

chartreuse3 

102 

205 

0 

RosyBrown3 

205 

155 

155 

chartreuse4 

69 

139 

0 

RosyBrown4 

139 

105 

105 

OliveDrabl 

192 

255 

62 

IndianRedl 

255 

106 

106 

OliveDrab2 

179 

238 

58 

IndianRed2 

238 

99 

99 

OliveDrabS 

154 

205 

50 

IndianRed3 

205 

85 

85 

OliveDraM 

105 

139 

34 

IndianRed4 

139 

58 

58 

DarkOliveGreenl 

202 

255 

112 

sienna  1 

255 

130 

71 

DarkOliveGreen2 

188 

238 

104 

sienna2 

238 

121 

66 

DarkOliveGreenS 

162 

205 

90 

sienna3 

205 

104 

57 

DarkOliveGreen4 

110 

139 

61 

sienna4 

139 

71 

38 

khaki  1 

255 

246 

143 

burly  wood  1 

255 

211 

155 

khaki2 

238 

230 

133 

burlywood2 

238 

197 

145 

khakiS 

205 

198 

115 

burlywood3 

205 

170 

125 

khaki4 

139 

134 

78 

burlywood4 

139 

115 

85 

LightGoldenrodl 

255 

236 

139 

wheat  1 

255 

231 

186 

LightGoldenrod2 

238 

220 

130 

wheat2 

238 

216 

174 

LightGoldenrod3 

205 

190 

112 

wheat3 

205 

186 

150 

LightGoldenrod4 

139 

129 

76 

wheat4 

139 

126 

102 

LightYellowl 

255 

255 

224 

tanl 

255 

165 

79 

LightYellow2 

238 

238 

209 

tan2 

238 

154 

73 

LightYellowS 

205 

205 

180 

tan3 

205 

133 

63 

LightYellow4 

139 

139 

122 

tan4 

139 

90 

43 

yellow  1 

255 

255 

0 

chocolate  1 

255 

127 

36 

yellow2 

238 

238 

0 

chocolate2 

238 

118 

33 

yellow3 

205 

205 

0 

chocolates 

205 

102 

29 

yellow4 

139 

139 

0 

chocolate4 

139 

69 

19 

goldl 

255 

215 

0 

firebrickl 

255 

48 

48 

gold2 

238 

201 

0 

firebrick2 

238 

44 

44 

gold3 

205 

173 

0 

firebricks 

205 

38 

38 

gold4 

139 

117 

0 

firebrick4 

139 

26 

26 
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Table  D-2.  The  R4  Color  Database  (continued) 


English  Words 

Red 

Green 

Blue 

English  Words 

Red 

Green 

Blue 

brown  1 

255 

64 

64 

HotPinkl 

255 

110 

180 

brown2 

238 

59 

59 

HotPink2 

238 

106 

167 

brown3 

205 

51 

51 

HotPink3 

205 

96 

144 

brown4 

139 

35 

35 

HotPink4 

139 

58 

98 

salmon  1 

255 

140 

105 

pinkl 

255 

181 

197 

salmon2 

238 

130 

98 

pink2 

238 

169 

184 

salmonS 

205 

112 

84 

pink3 

205 

145 

158 

salmon4 

139 

76 

57 

pink4 

139 

99 

108 

LightSalmonl 

255 

160 

122 

LightPinkl 

255 

174 

185 

LightS  almon2 

238 

149 

114 

LightPink2 

238 

162 

173 

LightSalmonS 

205 

129 

98 

LightPink3 

205 

140 

149 

LightSalmon4 

139 

87 

66 

LightPink4 

139 

95 

101 

orangel 

255 

165 

0 

PaleVioletRedl 

255 

130 

171 

orange2 

238 

154 

0 

PaleVioletRed2 

238 

121 

159 

orangeS 

205 

133 

0 

PaleVioletRed3 

205 

104 

137 

orange4 

139 

90 

0 

PaleVioletRed4 

139 

71 

93 

DarkOrangel 

255 

127 

0 

maroon  1 

255 

52 

179 

DarkOrange2 

238 

118 

0 

maroon2 

238 

48 

167 

DarkOrangeS 

205 

102 

0 

maroon3 

205 

41 

144 

DarkOrange4 

139 

69 

0 

maroon4 

139 

28 

98 

coral  1 

255 

114 

86 

VioletRedl 

255 

62 

150 

cora!2 

238 

106 

80 

VioletRed2 

238 

58 

140 

cora!3 

205 

91 

69 

VioletRed3 

205 

50 

120 

cora!4 

139 

62 

47 

VioletRed4 

139 

34 

82 

tomato  1 

255 

99 

71 

magenta  1 

255 

0 

255 

tomato2 

238 

92 

66 

magenta2 

238 

0 

238 

tomatoS 

205 

79 

57 

magenta3 

205 

0 

205 

tomato4 

139 

54 

38 

magenta4 

139 

0 

139 

OrangeRedl 

255 

69 

0 

orchid  1 

255 

131 

250 

OrangeRed2 

238 

64 

0 

orchid2 

238 

122 

233 

OrangeRedS 

205 

55 

0 

orchid3 

205 

105 

201 

OrangeRed4 

139 

37 

0 

orchid4 

139 

71 

137 

redl 

255 

0 

0 

pluml 

255 

187 

255 

red2 

238 

0 

0 

plum2 

238 

174 

238 

red3 

205 

0 

0 

plum3 

205 

150 

205 

red4 

139 

0 

0 

plum4 

139 

102 

139 

DeepPinkl 

255 

20 

147 

MediumOrchidl 

224 

102 

255 

DeepPink2 

238 

18 

137 

MediumOrchid2 

209 

95 

238 

DeepPink3 

205 

16 

118 

MediumOrchidS 

180 

82 

205 

DeepPink4 

139 

10 

80 

MediumOrchid4 

122 

55 

139 
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Table  D-2.  The  R< 
English  Words 

t  Color  L 
Red 

database* 
Green 

(continued) 
Blue 

DarkOrchidl 

191 

62 

255 

DarkOrchid2 

178 

58 

238 

DaikOrchidS 

154 

50 

205 

DarkOrchid4 

104 

34 

139 

purplel 

155 

48 

255 

purple2 

145 

44 

238 

purpleS 

125 

38 

205 

purple4 

85 

26 

139 

MediumPurplel 

171 

130 

255 

MediumPurple2 

159 

121 

238 

MediumPurpleS 

137 

104 

205 

MediumPurple4 

93 

71 

139 

thistlcl 

255 

225 

255 

thisUe2 

238 

210 

238 

thistleS 

205 

181 

205 

thistle4 

139 

123 

139 

''VIV  100»,speUedwith«d«c"or«  V.  "gmyO"  «  black  and 
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Event  Reference 


This  appendix  describes  each  event  structure  in  detail  and  briefly  shows  how  each  event  type 
is  used.  It  covers  the  most  common  uses  of  each  event  type,  the  information  contained  in 
each  event  structure,  how  the  event  is  selected,  and  the  side  effects  of  the  event,  if  any.  Each 
event  is  described  on  a  separate  reference  page. 

Table  E-l  lists  each  event  mask,  its  associated  event  types,  and  the  associated  structure  defi 
nition.  See  Chapter  8,  Events,  of  Volume  One,  Xlib  Programming  Manual,  for  more  informa 
tion  on  events. 

Table  E-1.  Event  Masks,  Event  Types,  and  Event  Structures 


Event  Mask 

Event  Type 

Structure 

KeyPressMask 

KeyPress 

XKeyPressedEvent 

KeyReleaseMask 

KeyRelease 

XKeyReleasedEvent 

ButtonPressMask 

ButtonPress 

XButtonPressedEvent 

ButtonReleaseMask 

ButtonRe  lease 

XButtonReleasedEvent 

Owner  GrabButtonMask 

n/a 

n/a 

KeymapStateMask 

KeymapNotify 

XKeymapEvent 

PointerMotionMask 

MotionNotify 

XPointerMovedEvent 

PointerMotionHintMask 

ButtonMotionMask 

ButtonlMotionMask 

Button2MotionMask 

ButtonSMotionMask 

Button4MotionMask 

ButtonSMotionMask 

EnterWindowMask 

EnterNotify 

XEnterWindowEvent 

LeaveWindowMask 

LeaveNotify 

XLeaveWindowEvent 

FocusChangeMask 

Focusln 

XFocusInEvent 

FocusOut 

XFocusOut  Event 
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Table  E-1.  Event  Masks,  Event  Types,  and  Event  Structures  (continued) 


Event  Mask 

Event  Type 

Structure 

ExposureMask 
selected  in  GC  by 

graphics  expose  member 

Expose 

GraphicsExpose 
NoExpose 

XExposeEvent 

XGraphicsExposeEvent 
XNoExposeEvent 

ColormapChangeMask 

ColormapNotify 

XColormapEvent 

PropertyChangeMask 

PropertyNotify 

XPropertyEvent 

VisibilityChangeMask 

VisibilityNotify 

XVisibilityEvent 

ResizeRedirectMask 

ResizeRequest 

XResizeRequestEvent 

StructureNotifyMask 

CirculateNotify 
ConfigureNotify 
DestroyNotify 
GravityNotify 
MapNotify 
ReparentNotify 
UnmapNotify 

XCirculateEvent 
XConfigureEvent 
XDestroyWindowEvent 
XGravityEvent 
XMapEvent 
XReparent  Event 
XUnmapEvent 

SubstructureNotifyMask 

CirculateNotify 
ConfigureNotify 
CreateNotify 
DestroyNotify 
GravityNotify 
MapNotify 
ReparentNotify 
UnmapNotify 

XCirculateEvent 
XConfigureEvent 
XCreateWindowEvent 
XDestroyWindowEvent 
XGravityEvent 
XMapEvent 
XReparentEvent 
XUnmapEvent 

Subs  tructureRedirect  Mask 

CirculateRequest 
Conf  igureRequest 
MapRequest 

XCirculateRequestEvent 
XConf  igureRequestEvent 
XMapRequest  Event 

(always  selected) 

MappingNotify 

XMappingEvent 

(always  selected) 

ClientMessage 

XClientMessageEvent 

(always  selected) 

SelectionClear 

XSetSelectClearEvent 

(always  selected) 

SelectionNotify 

XSelectionEvent 

(always  selected) 

Select  ionRequest 

XSelectionRequestEvent 
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E.1   Meaning  of  Common  Structure  Elements 

Example  E-l  shows  the  XEvent  union  and  a  simple  event  structure  that  is  one  member  of 
the  union.  Several  of  the  members  of  this  structure  are  present  in  nearly  every  event  struc 
ture.  They  are  described  here  before  we  go  into  the  event-specific  members  (see  also  Sec 
tion  8.2.2  of  Volume  One,  Xlib  Programming  Manual). 


Example  E-1.  XEvent  union  and  XAnyEvent  structure 


typedef  union  _XEvent  { 

int  type; 

XAnyEvent  xany; 

XButtonEvent  xbutton; 

XCirculateEvent  xcirculate; 

XCirculateRequestEvent  xcirculaterequest; 

XClientMessageEvent  xclient; 

XColormapEvent  xcolormap; 

XConf igureEvent  xconfigure; 

XConfigureRequestEvent  xconf igurerequest; 

XCr eat eWindowE vent  xcreatewindow; 

XDestroyWindowEvent  xdestroy window; 

XCrossingEvent  xcrossing; 

XExposeEvent  xexpose; 

XFocusChangeEvent  xfocus; 

XNoExposeEvent  xnoexpose; 

XGraphicsExposeE vent  xgraphicsexpose ; 

XGravityEvent  xgravity; 

XKeymapEvent  xkeymap; 

XKeyEvent  xkey; 

XMapEvent  xmap; 

XUnmapEvent  xunmap; 

XMappingEvent  xmapping; 

XMapRequestEvent  xmaprequest; 

XMotionEvent  xmotion; 

XPropertyEvent  xproperty; 

XReparentEvent  xreparent; 

XResizeRequest Event  xresizerequest ; 

XSelectionClearEvent  xselectionclear; 

XSelectionEvent  xselection; 

XSelectionRequest Event  xselectionrequest ; 

XVisibilityEvent  xvisibility; 
}  XEvent; 

typedef  struct  { 
int  type; 

unsigned  long  serial; 
Bool  send_event; 

Display  *display; 
Window  window; 

}  XAnyEvent  ; 


/*  Must  not  be  changed;  first  member  */ 


/*  #  of  last  request  processed  by  server  */ 

/*  True  if  this  came  from  SendEvent 

*  request  */ 

/*  Display  the  event  was  read  from  */ 

/*  window  on  which  event  was  requested 

*  in  event  mask  */ 
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The  first  member  of  the  XEvent  union  is  the  type  of  event  When  an  event  is  received  (with 
XNextEvent,  for  example),  the  application  checks  the  type  member  in  the  XEvent 
union.  Then  the  specific  event  type  is  known  and  the  specific  event  structure  (such  as 
xbutton)  is  used  to  access  information  specific  to  that  event  type. 

Before  the  branching  depending  on  the  event  type,  only  the  XEvent  union  is  used.  After 
the  branching,  only  the  event  structure  which  contains  the  specific  information  for  each  event 
type  should  be  used  in  each  branch.  For  example,  if  the  XEvent  union  were  called 
report,  the  report  .xexpose  structure  should  be  used  within  the  branch  for  Expose 
events. 

You  will  notice  that  each  event  structure  also  begins  with  a  type  member.  This  member  is 
rarely  used,  since  it  is  an  identical  copy  of  the  type  member  in  the  XEvent  union. 

Most  event  structures  also  have  a  window  member.  The  only  ones  that  do  not  are  selection 
events  (SelectionClear,  SelectionNotify,  and  SelectionRequest)  and 
events  selected  by  the  graphics_exposures  member  of  the  GC  (GraphicsExpose 
and  NoExpose).  The  window  member  indicates  the  event  window  that  selected  and 
received  the  event  This  is  the  window  where  the  event  arrives  if  it  has  propagated  through 
the  hierarchy  as  described  in  Section  8.3.2,  of  Volume  One,  Xlib  Programming  Manual.  One 
event  type  may  have  two  different  meanings  to  an  application,  depending  on  which  window 
it  appears  in. 

Many  of  the  event  structures  also  have  a  display  and/or  root  member.  The  display 
member  identifies  the  connection  to  the  server  that  is  active.  The  root  member  indicates 
which  screen  the  window  that  received  the  event  is  linked  to  in  the  hierarchy.  Most  programs 
only  use  a  single  screen  and  therefore  do  not  need  to  worry  about  the  root  member.  The 
display  member  can  be  useful,  since  you  can  pass  the  display  variable  into  routines  by 
simply  passing  a  pointer  to  the  event  structure,  eliminating  the  need  for  a  separate  display 
argument 

All  event  structures  include  a  serial  member  that  gives  the  nur  "  er  of  the  last  protocol 
request  processed  by  the  server.  This  is  useful  in  debugging,  since  an  error  can  be  detected 
by  the  server  but  not  reported  to  the  user  (or  programmer)  until  the  next  routine  that  gets  an 
event  That  means  several  routines  may  execute  successfully  after  the  error  occurs.  The  last 
request  processed  will  often  indicate  the  request  that  contained  the  error. 

All  event  structures  also  include  a  send_event  flag,  which,  if  True,  indicates  that  the 
event  was  sent  by  XSendEvent  (i.e.,  by  another  client  rather  than  by  the  server). 

The  following  pages  describe  each  event  type  in  detail.  The  events  are  presented  in  alphabet 
ical  order,  each  on  a  separate  page.  Each  page  describes  the  circumstances  under  which  the 
event  is  generated,  the  mask  used  to  select  it,  the  structure  itself,  its  members,  and  useful  pro 
gramming  notes.  Note  that  the  description  of  the  structure  members  does  not  include  those 
members  common  to  many  structures.  If  you  need  more  information  on  these  members, 
please  refer  to  this  introductory  section. 
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— xbutton- 


ButtonPress,  ButtonRelease 


When  Generated 

There  are  two  types  of  pointer  button  events:  ButtonPress  and  ButtonRelease.  Both 
contain  the  same  information. 

Select  With 

May  be  selected  separately,  using  ButtonPressMask  and  ButtonReleaseMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XButtonEvent  xbutton; 
}  XEvent; 


Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial; 
Bool  send_event; 
Display  ^display; 
Window  window; 
Window  root; 
Window  subwindow; 
Time  time; 
int  x,  y; 

int  x_root,  y_root; 
unsigned  int  state; 
unsigned  int  button; 
Bool  same_screen; 
}  XButtonEvent; 
typedef  XButtonEvent 
typedef  XButtonEvent 


/*  of  event  */ 

/*  #  of  last  request  processed  by  server  */ 

/*  True  if  this  came  from  a  SendEvent  request  * 

/*  Display  the  event  was  read  from  */ 

/*  event  window  it  is  reported  relative  to  */ 

/*  root  window  that  the  event  occurred  under  */ 

/*  child  window  */ 

/*  when  event  occurred,  in  milliseconds  */ 

/*  pointer  coordinates  relative  to  receiving 

*  window  */ 

/*  coordinates  relative  to  root  */ 

/*  mask  of  all  buttons  and  modifier  keys  */ 

/*  button  that  triggered  event  */ 

/*  same  screen  flag  */ 

XButtonPressedEvent; 
XButtonReleasedEvent ; 


Event  Structure  Members 

subwindow  If  the  source  window  is  the  child  of  the  receiving  window,  then  the 

subwindow  member  is  set  to  the  ID  of  that  child. 


time 


The  server  time  when  the  button  event  occurred,  in  milliseconds.  Time 
is  declared  as  unsigned  long,  so  it  wraps  around  when  it  reaches  the 
maximum  value  of  a  32-bit  number  (every  49.7  days). 

If  the  receiving  window  is  on  the  same  screen  as  the  root  window  speci 
fied  by  root,  then  x  and  y  are  the  pointer  coordinates  relative  to  the 
receiving  window's  origin.  Otherwise,  x  and  y  are  zero. 
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Button  Press,  Button  Release 


(continued) 


xbutton 


When  active  button  grabs  and  pointer  grabs  are  in  effect  (see  Section  9.4 
of  Volume  One,  Xlib  Programming  Manual),  the  coordinates  relative  to 
the  receiving  window  may  not  be  within  the  window  (they  may  be  nega 
tive  or  greater  than  window  height  or  width). 

x  root,  y_root  The  pointer  coordinates  relative  to  the  root  window  which  is  an  ancestor 
of  the  event  window.  If  the  pointer  was  on  a  different  screen,  these  are 
zero. 

state  The  state  of  all  the  buttons  and  modifier  keys  just  before  the  event, 

represented  by  a  mask  of  the  button  and  modifier  key  symbols: 

ButtonlMask,  Button2Mask,  ButtonSMask,  Button4Mask, 
ButtonSMask,  ControlMask,  LockMask,  ModlMask,  Mod2- 
Mask,  ModSMask,  Mod4Mask,  ModSMask,  and  ShiftMask.  If  a 
modifier  key  is  pressed  and  released  when  no  other  modifier  keys  are 
held,  the  ButtonPress  will  have  a  state  member  of  0  and  the 
ButtonRelease  will  have  a  nonzero  state  member  indicating  that 
itself  was  held  just  before  the  event 

button  A  value  indicating  which  button  changed  state  to  trigger  this  event  One 

of  the  constants:  Buttonl,  Button2,  Buttons,  Button4,  or 
Buttons. 

same_screen  Indicates  whether  the  pointer  is  currently  on  the  same  screen  as  this  win 
dow.  This  is  always  True  unless  the  pointer  was  actively  grabbed 
before  the  automatic  grab  could  take  place. 

Notes 

Unless  an  active  grab  already  exists  or  a  passive  grab  on  the  button  combination  that  was 
pressed  already  exists  at  a  higher  level  in  the  hierarchy  than  where  the  ButtonPress 
occurred,  an  automatic  active  grab  of  the  pointer  takes  place  when  a  ButtonPress  occurs. 
Because  of  the  automatic  grab,  the  matching  ButtonRelease  is  sent  to  the  same  application 
that  received  the  ButtonPress  event  If  OwnerGrabButtonMask  has  been  selected,  the 
ButtonRelease  event  is  delivered  to  the  window  which  contained  the  pointer  when  the 
button  was  released,  as  long  as  that  window  belongs  to  the  same  client  as  the  window  in  which 
the  ButtonPress  event  occurred.  If  the  ButtonRelease  occurs  outside  of  the  client's 
windows  or  OwnerGrabButtonMask  was  not  selected,  the  ButtonRelease  is  delivered 
to  the  window  in  which  the  ButtonPress  occurred.  The  grab  is  terminated  when  all  buttons 
are  released.  During  the  grab,  the  cursor  associated  with  the  grabbing  window  will  track  the 
pointer  anywhere  on  the  screen. 

If  the  application  has  invoked  a  passive  button  grab  on  an  ancestor  of  the  window  in  which  the 
ButtonPress  event  occurs,  then  that  grab  takes  precedence  over  the  automatic  grab,  and  the 
ButtonRelease  will  go  to  that  window,  or  it  will  be  handled  normally  by  that  client  depend 
ing  on  the  owner_events  flag  in  the  XGrabButton  call. 
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— xcirculate- 


CirculateNotify 


When  Generated 

A  CirculateNotify  event  reports  a  call  to  change  the  stacking  order,  and  it  includes 
whether  the  final  position  is  on  the  top  or  on  the  bottom.  This  event  is  generated  by 

XCirculateSubwindows,  XCirculateSubwindowsDown,  or  XCirculate- 
SubwindowsUp.  See  also  the  CirculateRequest  and  Conf igureNotify  reference 
pages. 

Select  With 

This  event  is  selected  with  StructureNotifyMask  in  the  XSelectlnput  call  for  the 
window  to  be  moved  or  with  SubstructureNotif  yMask  for  the  parent  of  the  window  to 
be  moved. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 
.  .  . 

XCirculateEvent  xcirculate; 

}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  *display; 

Window  event; 

Window  window; 

int  place; 
}  XCirculateEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request 
/*  Display  the  event  was  read  from  */ 


/*  PlaceOnTop,  PlaceOnBottom  */ 


*/ 


Event  Structure  Members 

event  The  window  receiving  the  event   If  the  event  was  selected  by  Structure 

NotifyMask,  event  will  be  the  same  as  window.  If  the  event  was  selected 
by  SubstructureNotif  yMask,  event  will  be  the  parent  of  window. 

window         The  window  that  was  restacked. 

place  Either  PlaceOnTop  or  PlaceOnBottom.  Indicates  whether  the  window  was 

raised  to  the  top  or  bottom  of  the  stack. 
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CirculateRequest  \ 


xcirculaterequest — 


When  Generated 

A  CirculateRequest  event  reports  when  XCirculateSubwindows,  XCirculate- 
SubwindowsDown,  XCirculateSubwindowsUp,  or  XRestackWindows  is  called  to 
change  the  stacking  order  of  a  group  of  children. 

This  event  differs  from  CirculateNotif  y  in  that  it  delivers  the  parameters  of  the  request 
before  it  is  carried  out  This  gives  the  client  that  selects  this  event  (usually  the  window  man 
ager)  the  opportunity  to  review  the  request  in  the  light  of  its  window  management  policy  before 
executing  the  circulate  request  itself  or  to  deny  the  request  (CirculateNotify  indicates 
the  final  outcome  of  the  request) 

Select  With 

This  event  is  selected  for  the  parent  window  with  SubstructureRedirectMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XCirculateRequestEvent  xcirculaterequest ; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;       /*  True  if  this  came  from  SendEvent  request  */ 

Display  ^display;      /*  Display  the  event  was  read  from  */ 

Window  parent; 

Window  window; 

int  place;  /*  PlaceOnTop,  PlaceOnBottom  */ 

}  XCirculateRequestEvent; 

Event  Structure  Members 

parent          The  parent  of  the  window  that  was  restacked.  This  is  the  window  that  selected 
the  event 

window          The  window  being  restacked. 

place  PlaceOnTop  or  PlaceOnBottom.  Indicates  whether  the  window  was  to  be 

placed  on  the  top  or  on  the  bottom  of  the  stacking  order. 
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J  ClientMessage 


When  Generated 

A  ClientMessage  event  is  sent  as  a  result  of  a  call  to  XSendEvent  by  a  client  to  a  particu 
lar  window.  Any  type  of  event  can  be  sent  with  XSendEvent,  but  it  will  be  distinguished 
from  normal  events  by  the  send_event  member  being  set  to  True.  If  your  program  wants  to 
be  able  to  treat  events  sent  with  XSendEvent  as  different  from  normal  events,  you  can  read 
this  member. 

Select  With 

There  is  no  event  mask  for  ClientMessage  events,  and  they  are  not  selected  with 
XSelect  Input.  Instead  XSendEvent  directs  them  to  a  specific  window,  which  is  given  as 
a  window  ID:  the  PointerWindow  or  the  inputFocus. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XClientMessageEvent  xclient; 
}  XEvent; 

Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send_event;       /*  True  if  this  came  from  SendEvent  request  */ 
Display  ^display;      /*  Display  the  event  was  read  from  */ 
Window  window; 
Atom  message_type; 
int  format; 
union  { 

char  b[20]; 

short  s[10] ; 

long  1[5]; 
}  data; 
}  XClientMessageEvent; 

Event  Structure  Members 

message_type  An  atom  that  specifies  how  the  data  is  to  be  interpreted  by  the  receiving 
client.  The  X  server  places  no  interpretation  on  the  type  or  the  data,  but 
it  must  be  a  list  of  8-bit,  16-bit,  or  32-bit  quantities,  so  that  the  X  server 
can  correctly  swap  bytes  as  necessary.  The  data  always  consists  of 
twenty  8-bit  values,  ten  16-bit  values,  or  five  32-bit  values,  although 
each  particular  message  might  not  make  use  of  all  of  these  values. 

format  Specifies  the  format  of  the  property  specified  by  message_type.  This 

will  be  on  of  the  values  8, 1 6,  or  32. 
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ColormapNotify 


X 


•xcolormap — 


When  Generated 

A  ColormapNotify  event  reports  when  the  colormap  attribute  of  a  window  changes  or 
when  the  colormap  specified  by  the  attribute  is  installed,  uninstalled,  or  freed.  This  event  is 
generated  by  XChangeWindowAttributes,  XFreeColormap,  XInstallColormap, 
and  XUninstallColormap. 

Select  With 

This  event  is  selected  with  ColormapChangeMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XColormapEvent  xcolormap; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  ^display; 

Window  window; 

Colormap  colormap; 

Bool  new; 

int  state; 
}  XColormapEvent; 


#  of  last  request  processed  by  server  */ 
True  if  this  came  from  SendEvent  request  */ 
Display  the  event  was  read  from  */ 

a  colormap  or  None  */ 

Colormaplnstalled,  ColormapUninstalled  */ 


Event  Structure  Members 

window          The  window  whose  associated  colormap  or  attribute  changes. 

colormap  The  colormap  associated  with  the  window,  either  a  colormap  ID  or  the  constant 
None.  It  will  be  None  only  if  this  event  was  generated  due  to  an  XFree 
Colormap  call. 

new  True  when  the  colormap  attribute  has  been  changed,  or  False  when  the  color- 

map  is  installed  or  uninstalled. 

state  Either  Colormaplnstalled  or  ColormapUninstalled;   it  indicates 

whether  the  colormap  is  installed  or  uninstalled. 
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ConfigureNotify 


When  Generated 

A  ConfigureNotify  event  announces  actual  changes  to  a  window's  configuration  (size, 
position,  border,  and  stacking  order).  See  also  the  CirculateRequest  reference  page. 

Select  With 

This  event  is  selected  for  a  single  window  by  specifying  the  window  ID  of  that  window  with 
StructureNotif yMask.  To  receive  this  event  for  all  children  of  a  window,  specify  the 
parent  window  ID  with  SubstructureNotif  yMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XConf igureEvent  xconfigure; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial 

Bool  send_event; 

Display  *display; 

Window  event; 

Window  window; 

int  x,  y; 

int  width,  height; 

int  border_width; 

Window  above; 

Bool  override_redirect; 
}  XConf igureEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request 
/*  Display  the  event  was  read  from  */ 


Event  Structure  Members 

event 


window 


width,  height 
border_width 
above 


The  window  that  selected  the  event  The  event  and  window 
members  are  identical  if  the  event  was  selected  with  Structure- 
Not  if  yMask. 

The  window  whose  configuration  was  changed. 

The  final  coordinates  of  the  reconfigured  window  relative  to  its  par 
ent. 

The  width  and  height  in  pixels  of  the  window  after  reconfiguration. 
The  width  in  pixels  of  the  border  after  reconfiguration. 

If  this  member  is  None,  then  the  window  is  on  the  bottom  of  the 
stack  with  respect  to  its  siblings.  Otherwise,  the  window  is  immedi 
ately  on  top  of  the  specified  sibling  window. 
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ConfigureNotify  (continued)  xconflgure 

override_redirect  The  override_redirect  attribute  of  the  reconfigured  window. 
If  True,  it  indicates  that  the  client  wants  this  window  to  be  immune 
to  interception  by  the  window  manager  of  configuration  requests. 
Window  managers  normally  should  ignore  this  event  if 

override  redirect  is  True. 
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—xconf  igurerequest- 


ConfigureRequest 


When  Generated 

A  ConfigureRequest  event  reports  when  another  client  attempts  to  change  a  window's 
size,  position,  border,  and/or  stacking  order. 

This  event  differs  from  Conf  igureNotif  y  in  that  it  delivers  the  parameters  of  the  request 
before  it  is  carried  out  This  gives  the  client  that  selects  this  event  (usually  the  window  man 
ager)  the  opportunity  to  revise  the  requested  configuration  before  executing  the 
XConf  igureWindow  request  itself  or  to  deny  the  request  (Conf  igureNotif  y  indicates 
the  final  outcome  of  the  request) 

Select  With 

This  event  is  selected  for  any  window  in  a  group  of  children  by  specifying  the  parent  window 
with  SubstructureRedirectMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XConf igureRequestEvent  xconf igurerequest ; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial 

Bool  send_event; 

Display  *display; 

Window  parent; 

Window  window; 

int  x,  y; 

int  width,  height; 

int  border_width; 

Window  above; 

int  detail; 

unsigned  long  value_mask 
}  XConf igureRequestEvent; 


#  of  last  request  processed  by  server  */ 
True  if  this  came  from  SendEvent  request 
Display  the  event  was  read  from  */ 


*/ 


/*  Above,  Below,  Bottomlf,  Toplf,  Opposite  */ 


Event  Structure  Members 

parent  The  window  that  selected  the  event  This  is  the  parent  of  the  window 

being  configured. 

window  The  window  that  is  being  configured. 

x,  y  The  requested  position  for  the  upper-left  pixel  of  the  window's  border 

relative  to  the  origin  of  the  parent  window. 

width,  height        The  requested  width  and  height  in  pixels  for  the  window. 
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ConfigureRequest 


(continued) 


xconfigurerequest 


border_width       The  requested  border  width  for  the  window. 

above  None,  Above,  Below,  Toplf ,  Bottomlf ,  or  Opposite.  Specifies 

the  sibling  window  on  top  of  which  the  specified  window  should  be 
placed.  If  this  member  has  the  constant  None,  then  the  specified  win 
dow  should  be  placed  on  the  bottom. 


Notes 


The  geometry  is  derived  from  the  XConf  igurewindow  request  that  triggered  the  event. 
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—xcreatewindow- 


CreateNotify 


When  Generated 

A  CreateNotify  event  reports  when  a  window  is  created. 

Select  With 

This  event  is  selected  on  children  of  a  window  by  specifying  the  parent  window  ID  with 
SubstructureNotifyMask.     (Note    that    this    event    type    cannot    be    selected    by 

StructureNotifyMask.) 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XCreateWindowEvent  xcreatewindow; 
}  XEvent; 


Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial;    /' 
Bool  send_event;         /' 

i 

Display  ^display;  /' 
Window  parent; 

Window  window;  /' 

int  x,  y;  /' 

int  width,  height;  /' 

int  border_width;  /' 
Bool  override_redirect;   /' 
}  XCreateWindowEvent; 


#  of  last  request  processed  by  server  */ 
True  if  this  came  from  SendEvent 
request  */ 

Display  the  event  was  read  from  */ 
/*  parent  of  the  window  */ 

window  ID  of  window  created  */ 

window  location  */ 

size  of  window  */ 

border  width  */ 

creation  should  be  overridden  */ 


Event  Structure  Members 

parent 
window 
x,y 

width, height 
border_width 
override  redirect 


The  ID  of  the  created  window's  parent 

The  ID  of  the  created  window. 

The  coordinates  of  the  created  window  relative  to  its  parent 

The  width  and  height  in  pixels  of  the  created  window. 

The  width  in  pixels  of  the  border  of  the  created  window. 

The  override_redirect  attribute  of  the  created  window.  If 
True,  it  indicates  that  the  client  wants  this  window  to  be  immune 
to  interception  by  the  window  manager  of  configuration  requests, 
managers  normally  should  ignore  this  event  if 


Window 

override 


redirect  is  True. 
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CreateNotify  (continued)  xcreatewlndow 

Notes 

For  descriptions  of  these  members,  see  the  XCreateWindow  function  and  the  XSet- 
WindowAttributes  structure. 
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— xdestroywindow  • 


DestroyNotify 


When  Generated 

A  DestroyNotify  event  reports  that  a  window  has  been  destroyed. 

Select  With 

To  receive  this  event  type  on  children  of  a  window,  specify  the  parent  window  ID  and  pass 
SubstructureNotifyMask  as  part  of  the  event_mask  argument  to  XSelect Input. 
This  event  type  cannot  be  selected  with  StructureNotif  yMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XDestroyWindowEvent  xdestroywindow; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  ^display; 

Window  event; 

Window  window; 
}  XDestroyWindowEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request  */ 
/*  Display  the  event  was  read  from  */ 


Event  Structure  Members 

event  The  window  that  selected  the  event 

window         The  window  that  was  destroyed. 
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EnterNotify,  LeaveNotify  \ 


When  Generated 

EnterNotify  and  LeaveNotify  events  occur  when  the  pointer  enters  or  leaves  a  window. 

When  the  pointer  crosses  a  window  border,  a  LeaveNotify  event  occurs  in  the  window 
being  left  and  an  EnterNotify  event  occurs  in  the  window  being  entered.  Whether  or  not 
each  event  is  queued  for  any  application  depends  on  whether  any  application  selected  the  right 
event  on  the  window  in  which  it  occurred. 

In  addition,  EnterNotify  and  LeaveNotify  events  are  delivered  to  windows  that  are 
virtually  crossed.  These  are  windows  that  are  between  the  origin  and  destination  windows  in 
the  hierarchy  but  not  necessarily  on  the  screen.  Further  explanation  of  virtual  crossing  is  pro 
vided  two  pages  following. 

Select  With 

Each  of  these  events  can  be  selected  separately  with  XEnterWindowMask  and  XLeave- 
WindowMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XCrossingEvent  xcrossing; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type;  /*  of  event  */ 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;  /*  True  if  this  came  from  SendEvent  request  */ 

Display  *display;  /*  Display  the  event  was  read  from  */ 

Window  window;  /*  event  window  it  is  reported  relative  to  */ 

Window  root;  /*  root  window  that  the  event  occurred  on  */ 

Window  subwindow;  /*  child  window  */ 

Time  time;  /*  milliseconds  */ 

int  x,  y;  /*  pointer  x,y  coordinates  in  receiving 

*  window  */ 

int  x_root,  y_root;    /*  coordinates  relative  to  root  */ 

int  mode;  /*  NotifyNormal,  NotifyGrab,  NotifyUngrab  */ 

int  detail;  /*  NotifyAncestor,  Notifylnferior, 

*  NotifyNonLinear,  NotifyNonLinearVirtual, 

*  NotifyVirtual  */ 

Bool  same_screen;      /*  same  screen  flag  */ 
Bool  focus;  /*  boolean  focus  */ 

unsigned  int  state;    /*  key  or  button  mask  */ 

}  XCrossingEvent; 

typedef  XCrossingEvent  XEnterWindowEvent; 

typedef  XCrossingEvent  XLeaveWindowEvent; 
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Event  Structure  Members 

The  following  list  describes  the  members  of  the  XGrossingEvent  structure. 

subwindow  In  a  LeaveNotify  event,  if  the  pointer  began  in  a  child  of  the  receiv 

ing  window,  then  the  child  member  is  set  to  the  window  ID  of  the 
child.  Otherwise,  it  is  set  to  None.  For  an  EnterNotify  event,  if  the 
pointer  ends  up  in  a  child  of  the  receiving  window,  then  the  child 
member  is  set  to  the  window  ID  of  the  child.  Otherwise,  it  is  set  to 
None. 


time 


The  server  time  when  the  crossing  event  occurred,  in  milliseconds. 
Time  is  declared  as  unsigned  long,  so  it  wraps  around  when  it 
reaches  the  maximum  value  of  a  32-bit  number  (every  49.7  days). 

x,  y  The  point  of  entry  or  exit  of  the  pointer  relative  to  the  event  window. 

x_root ,  y_root      The  point  of  entry  or  exit  of  the  pointer  relative  to  the  root  window. 

mode  Normal  crossing  events  or  those  caused  by  pointer  warps  have  mode 

NotifyNormal,  events  caused  by  a  grab  have  mode  NotifyGrab, 
and  events  caused  by  a  released  grab  have  mode  Not  if  yUngrab. 

detail  The  value  of  the  detail  member  depends  on  the  hierarchical  relation 

ship  between  the  origin  and  destination  windows  and  the  direction  of 
pointer  transfer.  Determining  which  windows  receive  events  and  with 
which  detail  members  is  quite  complicated.  This  topic  is  described  in 
the  next  section. 

same_screen  Indicates  whether  the  pointer  is  currently  on  the  same  screen  as  this  win 
dow.  This  is  always  True  unless  the  pointer  was  actively  grabbed 
before  the  automatic  grab  could  take  place. 

focus  If  the  receiving  window  is  the  focus  window  or  a  descendant  of  the  focus 

window,  the  focus  member  is  True;  otherwise,  it  is  False. 

state  The  state  of  all  the  buttons  and  modifier  keys  just  before  the  event, 

represented  by  a  mask  of  the  button  and  modifier  key  symbols: 

ButtonlMask,  Button2Mask,  ButtonSMask,  Button4Mask, 
ButtonSMask,  ControlMask,  LockMask,  ModlMask,  Mod2- 
Mask,  ModSMask,  Mod4Mask,  ModSMask,  and  Shif  tMask. 

Virtual  Crossing  and  the  detail  Member 

Virtual  crossing  occurs  when  the  pointer  moves  between  two  windows  that  do  not  have  a 
parent-child  relationship.  Windows  between  the  origin  and  destination  windows  in  the  hierar 
chy  receive  EnterNotify  and  LeaveNotify  events.  The  detail  member  of  each  of 
these  events  depends  on  the  hierarchical  relationship  of  the  origin  and  destination  windows  and 
the  direction  of  pointer  transfer. 
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Virtual  crossing  is  an  advanced  topic  that  you  should  not  spend  time  figuring  out  unless  you 
have  an  important  reason  to  use  it  We  have  never  seen  an  application  that  uses  this  feature, 
and  we  know  of  no  reason  for  its  extreme  complexity.  With  that  word  of  warning,  proceed. 

Let's  say  the  pointer  has  moved  from  one  window,  the  origin,  to  another,  the  destination.  First, 
we'll  specify  what  types  of  events  each  window  gets  and  then  the  detail  member  of  each  of 
those  events. 

The  window  of  origin  receives  a  LeaveNotify  event  and  the  destination  window  receives  an 
EnterNotify  event,  if  they  have  requested  this  type  of  event  If  one  is  an  inferior  of  the 
other,  the  detail  member  of  the  event  received  by  the  inferior  is  Notif  yAncestor  and  the 
detail  of  the  event  received  by  the  superior  is  Notif  y inferior.  If  the  crossing  is  between 
parent  and  child,  these  are  the  only  events  generated. 

However,  if  the  origin  and  destination  windows  are  not  parent  and  child,  other  windows  are 
virtually  crossed  and  also  receive  events.  If  neither  window  is  an  ancestor  of  the  other, 
ancestors  of  each  window,  up  to  but  not  including  the  least  common  ancestor,  receive  Leave- 
Notif y  events,  if  they  are  in  the  same  branch  of  the  hierarchy  as  the  origin,  and  Enter- 
Notify  events,  if  they  are  in  the  same  branch  as  the  destination.  These  events  can  be  used  to 
track  the  motion  of  the  pointer  through  the  hierarchy. 

•  In  the  case  of  a  crossing  between  a  parent  and  a  child  of  a  child,  the  middle  child  receives  a 

LeaveNotify  with  detail  Notif yVirtual. 

•  In  the  case  of  a  crossing  between  a  child  and  the  parent  of  its  parent,  the  middle  child 
receives  an  EnterNotify  with  detail  Notif  yVirtual. 

•  In  a  crossing  between  windows  whose  least  common  ancestor  is  two  or  more  windows 
away,  both  the  origin  and  destination  windows  receive  events  with  detail  Not  if  y- 
Nonlinear.  The  windows  between  the  origin  and  the  destination  in  the  hierarchy,  up  to 
but  not  including  their  least  common  ancestor,  receive  events  with  detail  Not  if  y- 
NonlinearVirtual.  The  least  common  ancestor  is  the  lowest  window  from  which  both 
are  descendants. 

•  If  the  origin  and  destination  windows  are  on  separate  screens,  the  events  and  details  gen 
erated  are  the  same  as  for  two  windows  not  parent  and  child,  except  that  the  root  windows 
of  the  two  screens  are  considered  the  least  common  ancestor.  Both  root  windows  also 
receive  events. 


6 18  Xlib  Reference  Manual 


xcrossing 


(continued) 


EnterNotify,  LeaveNotify 


Table  E-l  shows  the  event  types  generated  by  a  pointer  crossing  from  window  A  to  window  B 
when  window  C  is  the  least  common  ancestor  of  A  and  B. 

Table  E-1.  Border  Crossing  Events  and  Window  Relationship 


LeaveNotify 


Origin  window  (A) 

Windows  between  A  and  B, 
exclusive,  if  A  is  inferior 

Windows  between  A  and  C, 
exclusive 

Root  window  on  screen  of 
origin  if  different  from 
screen  of  destination 


EnterNotify 


Destination  window  (5) 

Windows  between  A  and  B,  exclusive,  if  B  is  inferior 

Windows  between  B  and  C,  exclusive, 

Root  window  on  screen  of  destination  if  different 
from  screen  of  origin 


Table  E-2  lists  the  detail  members  in  events  generated  by  a  pointer  crossing  from  window  A 
to  window  B. 

Table  E-2.  Event  detail  Member  and  Window  Relationship 
de  t  a  i  1  Rag  Window  Delivered  To 


NotifyAncestor 
Notify Inferior 
NotifyVirtual 

NotifyNonlinear 
NotifyNonlinearVirtual 


Origin  or  destination  when  either  is  descendant 
Origin  or  destination  when  either  is  ancestor 

Windows  between  A  and  B,  exclusive,  if  either  is 
descendant 

Origin  and  destination  when  A  and  B  are  two  or  more 
windows  distant  from  least  common  ancestor  C 

Windows  between  A  and  C,  exclusive,  and  between 
B  and  C,  exclusive,  when  A  and  B  have  least  common 
ancestor  C;  also  on  both  root  windows  if  A  and  B  are 
on  different  screens 
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For  example,  Figure  E-l  shows  the  events  that  are  generated  by  a  movement  from  a  window 
(window  A)  to  a  child  (window  Bl)  of  a  sibling  (window  B).  This  would  generate  three  events: 
a  LeaveNotify  with  detail  Notif  yNonlinear  for  the  window  A,  an  EnterNotify  with 
detail  Notif yNonlinearVirtual  for  its  sibling  window  5,  and  an  EnterNotify  with 
detail  Notif  yNonlinear  for  the  child  (window  Bl). 


Root  Window 

(no  event) 

I        I 

\ 

— 

•w 

~~l 

A 

LeaveNotify  event  with  detail 

Not  if  yNonlinear 

B 

EnterNotify  event  with  detail 

Not  if  yNonlinearVirtual 

1 

I 

A1 

no  event 

B1 

EnterNc 
Notify! 

3tify  event  with  detail 

Nonlinear 

Figure  E-1.  Events  generated  by  a  move  between  windows 

EnterNotify  and  LeaveNotify  events  are  also  generated  when  the  pointer  is  grabbed,  if 
the  pointer  was  not  already  inside  the  grabbing  window.  In  this  case,  the  grabbing  window 
receives  an  EnterNotify  and  the  window  containing  the  pointer  receives  a  LeaveNotify 
event,  both  with  mode  Notif yUngrab.  The  pointer  position  in  both  events  is  the  position 
before  the  grab.  The  result  when  the  grab  is  released  is  exactly  the  same,  except  that  the  two 
windows  receive  EnterNotify  instead  of  LeaveNotify  and  vice  versa. 
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Figure  E-2  demonstrates  the  events  and  details  caused  by  various  pointer  transitions,  indicated 
by  heavy  arrows. 


LeaveNotify 
Ancestor 


Figure  E-2.  Border  crossing  events  and  detail  member  for  pointer  movement  from 
window  A  to  window  B,  for  various  window  relationships 
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When  Generated 

An  Expose  event  is  generated  when  a  window  becomes  visible  or  a  previously  invisible  part 
of  a  window  becomes  visible.  Only  inputOutput  windows  generate  or  need  to  respond  to 
Expose  events;  inputOnly  windows  never  generate  or  need  to  respond  to  them.  The 
Expose  event  provides  the  position  and  size  of  the  exposed  area  within  the  window  and  a 
rough  count  of  the  number  of  remaining  exposure  events  for  the  current  window. 

Select  With 

This  event  is  selected  with  ExposureMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XExposeEvent  xexpose; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;       /*  True  if  this  came  from  SendEvent  request  */ 

Display  ^display;     /*  Display  the  event  was  read  from  */ 

Window  window; 

int  x,  y; 

int  width,  height; 

int  count;  /*  If  nonzero,  at  least  this  many  more  */ 

}  XExposeEvent; 

Event  Structure  Members 

x,  y  The  coordinates  of  the  upper-left  corner  of  the  exposed  region  relative  to 

the  origin  of  the  window. 

width,  height        The  width  and  height  in  pixels  of  the  exposed  region. 

count  The  approximate  number  of  remaining  contiguous  Expose  events  that 

were  generated  as  a  result  of  a  single  function  call. 

Notes 

A  single  action  such  as  a  window  movement  or  a  function  call  can  generate  several  exposure 
events  on  one  window  or  on  several  windows.  The  server  guarantees  that  all  exposure  events 
generated  from  a  single  action  will  be  sent  contiguously,  so  that  they  can  all  be  handled  before 
moving  on  to  other  event  types.  This  allows  an  application  to  keep  track  of  the  rectangles 
specified  in  contiguous  Expose  events,  set  the  clip_mask  in  a  GC  to  the  areas  specified  in 
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the  rectangle  using  XSetRegion  or  XSetClipRectangles,  and  then  finally  redraw  the 
window  clipped  with  the  GC  in  a  single  operation  after  all  the  Expose  events  have  arrived. 
The  last  event  to  arrive  is  indicated  by  a  count  of  0.  In  Release  2,  XUnionRectwith- 
Region  can  be  used  to  add  the  rectangle  in  Expose  events  to  a  region  before  calling  XSet 
Region. 

If  your  application  is  able  to  redraw  partial  windows,  you  can  also  read  each  exposure  event  in 
turn  and  redraw  each  area. 
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When  Generated 

Focusln  and  FocusOut  events  occur  when  the  keyboard  focus  window  changes  as  a  result 
of  an  XSetlnputFocus  call.  They  are  much  like  EnterNotify  and  LeaveNotify 
events  except  that  they  track  the  focus  rather  than  the  pointer. 

When  a  focus  change  occurs,  a  FocusOut  event  is  delivered  to  the  old  focus  window  and  a 
Focusln  event  to  the  window  which  receives  the  focus.  In  addition,  windows  in  between 
these  two  windows  in  the  window  hierarchy  are  virtually  crossed  and  receive  focus  change 
events,  as  described  below.  Some  or  all  of  the  windows  between  the  window  containing  the 
pointer  at  the  time  of  the  focus  change  and  the  root  window  also  receive  focus  change  events, 
as  described  below. 

Select  With 

Focusln  and  FocusOut  events  are  selected  with  FocusChangeMask.  They  cannot  be 
selected  separately. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XFocusChangeEvent  xfocus; 
(... 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type;  /*  Focusln  or  FocusOut  */ 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;       /*  True  if  this  came  from  SendEvent  request  */ 

Display  ^display;     /*  Display  the  event  was  read  from  */ 

Window  window;        /*  Window  of  event  */ 

int  mode;  /*  NotifyNormal,  NotifyGrab,  NotifyUngrab  */ 

int  detail;  /*  NotifyAncestor,  NotifyDetailNone, 

*  Notifylnferior,  NotifyNonLinear, 

*  NotifyNonLinearVirtual,  NotifyPointer, 

*  NotifyPointerRoot,  NotifyVirtuaW 
}  XFocusChangeEvent; 

typedef  XFocusChangeEvent  XFocusInEvent; 
typedef  XFocusChangeEvent  XFocusOutEvent; 

Event  Structure  Members 

mode  For  events  generated  when  the  keyboard  is  not  grabbed,  mode  is  Notify 

Normal;  when  the  keyboard  is  grabbed,  mode  is  NotifyGrab;  and  when  a 
keyboard  is  ungrabbed,  mode  is  NotifyUngrab. 

detail  The  detail  member  identifies  the  relationship  between  the  window  that 
receives  the  event  and  the  origin  and  destination  windows.  It  will  be  described 
in  detail  after  the  description  of  which  windows  get  what  types  of  events. 
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Notes 

The  keyboard  focus  is  a  window  that  has  been  designated  as  the  one  to  receive  all  keyboard 
input  irrespective  of  the  pointer  position.  Only  the  keyboard  focus  window  and  its  descendants 
receive  keyboard  events.  By  default,  the  focus  window  is  the  root  window.  Since  all  windows 
are  descendants  of  the  root,  the  pointer  controls  the  window  that  receives  input. 

Most  window  managers  allow  the  user  to  set  a  focus  window  to  avoid  the  problem  where  the 
pointer  sometimes  gets  bumped  into  the  wrong  window  and  your  typing  does  not  go  to  the 
intended  window.  If  the  pointer  is  pointing  at  the  root  window,  all  typing  is  usually  lost,  since 
there  is  no  application  for  this  input  to  propagate  to.  Some  applications  may  set  the  keyboard 
focus  so  that  they  can  get  all  keyboard  input  for  a  given  period  of  time,  but  this  practice  is  not 
encouraged. 

Focus  events  are  used  when  an  application  wants  to  act  differently  when  the  keyboard  focus  is 
set  to  another  window  or  to  itself.  Focus ChangeMask  is  used  to  select  Focusln  and 
FocusOut  events. 

When  a  focus  change  occurs,  a  FocusOut  event  is  delivered  to  the  old  focus  window  and  a 
Focusln  event  is  delivered  to  the  window  which  receives  the  focus.  Windows  in  between  in 
the  hierarchy  are  virtually  crossed  and  receive  one  focus  change  event  each  depending  on  the 
relationship  and  direction  of  transfer  between  the  origin  and  destination  windows.  Some  or  all 
of  the  windows  between  the  window  containing  the  pointer  at  the  time  of  the  focus  change  and 
that  window's  root  window  can  also  receive  focus  change  events.  By  checking  the  detail 
member  of  Focusln  and  FocusOut  events,  an  application  can  tell  which  of  its  windows  can 
receive  input. 

The  detail  member  gives  clues  about  the  relationship  of  the  event  receiving  window  to  the 
origin  and  destination  of  the  focus.  The  detail  member  of  Focus  in  and  FocusOut  events 
is  analogous  to  the  detail  member  of  EnterNotif y  and  LeaveNotif y  events  but  with 
even  more  permutations  to  make  life  complicated. 

Virtual  Focus  Crossing  and  the  detail  Member 

We  will  now  embark  on  specifying  the  types  of  events  sent  to  each  window  and  the  detail 
member  in  each  event,  depending  on  the  relative  position  in  the  hierarchy  of  the  origin  window 
(old  focus),  destination  window  (new  focus),  and  the  pointer  window  (window  containing 
pointer  at  time  of  focus  change).  Don't  even  try  to  figure  this  out  unless  you  have  to. 
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Table  E-3  shows  the  event  types  generated  by  a  focus  transition  from  window  A  to  window  B 
when  window  C  is  the  least  common  ancestor  of  A  and  B.  This  table  includes  most  of  the 
events  generated,  but  not  all  of  them.  It  is  quite  possible  for  a  single  window  to  receive  more 
than  one  focus  change  event  from  a  single  focus  change. 

Table  E-3.  Focusln  and  FocusOut  Events  and  Window  Relationship 


FocusOut 


Origin  window  (A) 

Windows  between  A  and  5, 
exclusive,  if  A  is  inferior 

Windows  between  A  and  C, 
exclusive 

Root  window  on  screen  of 
origin  if  different  from 
screen  of  destination 

Pointer  window  up  to  but 
not  including  origin  window 
if  pointer  window  is  descen 
dant  of  origin 

Pointer  window  up  to  and 
including  pointer  window's 
root  if  transfer  was  from 

PointerRoot 


Focusln 


Destination  window  (B) 

Windows  between  A  and  5,  exclusive,  if  B  is  inferior 

Windows  between  B  and  C,  exclusive 

Root  window  on  screen  of  destination  if  different 
from  screen  of  origin 

Pointer  window  up  to  but  not  including  destination 
window  if  pointer  window  is  descendant  of  destina 
tion 

Pointer  window  up  to  and  including  pointer  win 
dow's  root  if  transfer  was  to  PointerRoot 
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Table  E-4  lists  the  detail  members  in  events  generated  by  a  focus  transition  from  window  A 
to  window  B  when  window  C  is  the  least  common  ancestor  of  A  and  B,  with  P  being  the  win 
dow  containing  the  pointer. 

Table  E-4.  Event  detail  Member  and  Window  Relationship 


detail  Flag 


NotifyAncestor 
Notifylnferior 
NotifyVirtual 

NotifyNonlinear 
NotifyNonlinearVirtual 

NotifyPointer 
NotifyPointerRoot 

NotifyDetailNone 


Window  Deli vered  To 


Origin  or  destination  when  either  is  descendant 
Origin  or  destination  when  either  is  ancestor 

Windows  between  A  and  B,  exclusive,  if  either  is 
descendant 

Origin  and  destination  when  A  and  B  are  two  or  more 
windows  distant  from  least  common  ancestor  C 

Windows  between  A  and  C,  exclusive,  and  between 
B  and  C,  exclusive,  when  A  and  B  have  least  common 
ancestor  C;  also  on  both  root  windows  if  A  and  B  are 
on  different  screens 

Window  P  and  windows  up  to  but  not  including  the 
origin  or  destination  windows 

Window  P  and  all  windows  up  to  its  root,  and  all 
other  roots,  when  focus  is  set  to  or  from  Pointer- 
Root 

All  roots,  when  focus  is  set  to  or  from  None 


Figure  E-3  shows  all  the  possible  combinations  of  focus  transitions  and  of  origin,  destination, 
and  pointer  windows  and  shows  the  types  of  events  that  are  generated  and  their  detail  mem 
ber.  Solid  lines  indicate  branches  of  the  hierarchy.  Dotted  arrows  indicate  the  direction  of 
transition  of  the  focus.  At  each  end  of  this  arrow  are  the  origin  and  destination  windows,  win 
dows  A  to  B.  Arrows  ending  in  a  bar  indicate  that  the  event  type  and  detail  described  are 
delivered  to  all  windows  up  to  the  bar. 

In  any  branch,  there  may  be  windows  that  are  not  shown.  Windows  in  a  single  branch  between 
two  boxes  shown  will  get  the  event  types  and  details  shown  beside  the  branch. 
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LeaveNotify, 


If  window  P  is  between  A 
and  B,  windows  from  P  up 
to  but  not  including  B  get 
FOCUS  in  with  detail 

Notifylnterior 


FocusOut, 

Nonlinear-Virtual 


1 


Roots  of  other  Screens: 
FOCUS:.-,  with  Detail  :;or.f 


Root  Window 

FOCUS:  None 


FocusOut, 

y 


Figure  E-3.    Focusln  and  FocusOut  event  schematics 
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Roots  of  other  Screens: 
isOut  with  Detail  PointerRoot 


Focus: 

PointerP.cot    I 


1 

T 


Roots  of  other  Screens: 

"ocusGut  with  Detail  •;•  n< 


Root  Window 
FOCUS:  Kone 


Focus  change  from  PointerRoot  to  : 

All  Root  Windows: 
2ui  with  Detail  E    int  erF 


Pointer's 
Root  Window 


1       _J 


Focus  change  from  PointerRoot  to  ::.:.• 


All  Root  Windows: 
:  -  with  Detail  No. 


Pointer's 
Root  Window 


Figure  E-3.    Focusln  and  FocusOut  event  schematics  (cont.) 

Focusln  and  FocusOut  events  are  also  generated  when  the  keyboard  is  grabbed,  if  the  focus 
was  not  already  assigned  to  the  grabbing  window.  In  this  case,  all  windows  receive  events  as  if 
the  focus  was  set  from  the  current  focus  to  the  grab  window.  When  the  grab  is  released,  the 
events  generated  are  just  as  if  the  focus  was  set  back. 
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When  Generated 

GraphicsExpose  events  indicate  that  the  source  area  for  a  XCopyArea  or  XCopyPlane 
request  was  not  available  because  it  was  outside  the  source  window  or  obscured  by  a  window. 
NoExpose  events  indicate  that  the  source  region  was  completely  available. 

Select  With 

These  events  are  not  selected  with  xselect  Input  but  are  sent  if  the  GC  in  the  XCopyArea 
or  XCopyPlane  request  had  its  graphics_exposures  flag  set  to  True.  If 
graphics_exposures  is  True  in  the  GC  used  for  the  copy,  either  one  NoExpose  event 
or  one  or  more  GraphicsExpose  events  will  be  generated  for  every  XCopyArea  or 
XCopyPlane  call  made. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XNoExposeEvent  xnoexpose; 
XGraphicsExposeEvent  xgraphicsexpose ; 

}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  *display; 

Drawable  drawable; 

int  x,  y; 

int  width,  height; 

int  count; 

int  major_code; 

int  minor_code; 
}  XGraphicsExposeEvent; 

typedef  struct  { 

int  type; 

unsigned  long  serial; 

Bool  send_event; 

Display  *display; 

Drawable  drawable; 

int  ma jor_code; 

int  minor_code; 
}  XNoExposeEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request 
/*  Display  the  event  was  read  from  */ 


/*  if  nonzero,  at  least  this  many  more  */ 
/*  core  is  CopyArea  or  CopyPlane  */ 
/*  not  defined  in  the  core  */ 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request  */ 
/*  Display  the  event  was  read  from  */ 

/*  core  is  CopyArea  or  CopyPlane  */ 
/*  not  defined  in  the  core  */ 
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GraphicsExpose,  NoExpose 


xnoexpose 


Event  Structure  Members 

drawable  A  window  or  an  off-screen  pixmap.  This  specifies  the  destination  of  the 

graphics  request  that  generated  the  event 

x,  y  The  coordinates  of  the  upper-left  corner  of  the  exposed  region  relative  to 

the  origin  of  the  window. 

width,  height        The  width  and  height  in  pixels  of  the  exposed  region. 

count  The  approximate  number  of  remaining  contiguous  GraphicsExpose 

events  that  were  generated  as  a  result  of  the  xcopyArea  or  XGopy- 
P lane  call. 

ma  jor_code  The  graphics  request  used.  This  may  be  one  of  the  symbols  CopyArea 

or  CopyPlane  or  a  symbol  defined  by  a  loaded  extension. 

minor_code  Zero  unless  the  request  is  part  of  an  extension. 

Notes 

Expose  events  and  GraphicsExpose  events  both  indicate  the  region  of  a  window  that  was 
actually  exposed  (x,  y,  width,  and  height).  Therefore,  they  can  often  be  handled  similarly. 
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GravityNotify  \ 


•xgravity — 


When  Generated 

A  GravityNotify  event  reports  when  a  window  is  moved  because  of  a  change  in  the  size  of 
its  parent  This  happens  when  the  win_gravity  attribute  of  the  child  window  is  something 
other  than  StaticGravity  or  UnmapGravity. 

Select  With 

This  event  is  selected  for  a  single  window  by  specifying  the  window  ID  of  that  window  with 
St  ructureNotif  yMask.  To  receive  notification  of  movement  due  to  gravity  for  a  group  of 
siblings,  specify  the  parent  window  ID  with  SubstructureNotif  yMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XGravityEvent  xgravity; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;       /*  True  if  this  came  from  SendEvent  request  */ 

Display  *display;      /*  Display  the  event  was  read  from  */ 

Window  event; 

Window  window; 

int  x,  y; 
}  XGravityEvent; 

Event  Structure  Members 

event  The  window  that  selected  the  event 

window          The  window  that  was  moved. 

x,  y  The  new  coordinates  of  the  window  relative  to  its  parent 
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—xkeymap- 


KeymapNotify 


When  Generated 

A  KeymapNotify  event  reports  the  state  of  the  keyboard  and  occurs  when  the  pointer  or 
keyboard  focus  enters  a  window.  KeymapNotify  events  are  reported  immediately  after 
EnterNotify  or  Focusln  events.  This  is  a  way  for  the  application  to  read  the  keyboard 
state  as  the  application  is  "woken  up,"  since  the  two  triggering  events  usually  indicate  that  the 
application  is  about  to  receive  user  input. 

Select  With 

This  event  is  selected  with  KeymapStateMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XKeymapEvent  xkeymap; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  *display; 

Window  window; 

char  key_vector[32] ; 
}  XKeymapEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request  */ 
/*  Display  the  event  was  read  from  */ 


Event  Structure  Members 

window  Reports  the  window  which  was  reported  in  the  window  member  of  the  pre 

ceding  EnterNotify  or  Focusln  event 

key_vector  A  bit  vector  or  mask,  each  bit  representing  one  physical  key,  with  a  total  of 
256  bits.  For  a  given  key,  its  keycode  is  its  position  in  the  keyboard  vector. 
You  can  also  get  this  bit  vector  by  calling  XQueryKeymap. 

Notes 

The  serial  member  of  KeymapNotify  does  not  contain  the  serial  number  of  the  most 
recent  protocol  request  processed,  because  this  event  always  follows  immediately  after 
EnterNotify  or  Focusln  events  in  which  the  serial  member  is  valid. 
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KeyPress,  KeyRelease 


X 


•xkey — 


When  Generated 

KeyPress  and  KeyRelease  events  are  generated  for  all  keys,  even  those  mapped  to 
modifier  keys  such  as  Shift  or  Control. 

Select  With 

Each  type  of  keyboard  event  may  be  selected  separately  with  KeyPressMask  and  Key- 
ReleaseMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XKeyEvent  xkey; 
}  XEvent; 


Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial, 
Bool  send_event; 
Display  *display; 
Window  window; 
Window  root; 
Window  subwindow; 
Time  time; 
int  x,  y; 


int  x_root,  y_root; 

unsigned  int  state; 

unsigned  int  keycode; 

Bool  same_screen; 
}  XKeyEvent; 

typedef  XKeyEvent  XKeyPressedEvent; 
typedef  XKeyEvent  XKeyReleasedEvent; 


/*  of  event  */ 

/*  #  of  last  request  processed  by  server  */ 

/*  True  if  this  came  from  SendEvent  request  */ 

/*  Display  the  event  was  read  from  */ 

/*  event  window  it  is  reported  relative  to  */ 

/*  root  window  that  the  event  occurred  on  */ 

/*  child  window  */ 

/*  milliseconds  */ 

/*  pointer  coordinates  relative  to  receiving 

*  window  */ 

/*  coordinates  relative  to  root  */ 

/*  modifier  key  and  button  mask  */ 

/*  server-dependent  code  for  key  */ 

/*  same  screen  flag  */ 


Event  Structure  Members 

subwindow  If  the  source  window  is  the  child  of  the  receiving  window,  then  the 

subwindow  member  is  set  to  the  ID  of  that  child. 


time 


x,y 


The  server  time  when  the  button  event  occurred,  in  milliseconds.  Time 
is  declared  as  unsigned  long,  so  it  wraps  around  when  it  reaches  the 
maximum  value  of  a  32-bit  number  (every  49.7  days). 

If  the  receiving  window  is  on  the  same  screen  as  the  root  window  speci 
fied  by  root,  then  x  and  y  are  the  pointer  coordinates  relative  to  the 
receiving  window's  origin.  Otherwise,  x  and  y  are  zero. 
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(continued) 


KeyPress,  KeyRelease 


When  active  button  grabs  and  pointer  grabs  are  in  effect  (see  Section  9.4 
of  Volume  One,  Xlib  Programming  Manual),  the  coordinates  relative  to 
the  receiving  window  may  not  be  within  the  window  (they  may  be  nega 
tive  or  greater  than  window  height  or  width). 

xjcoot,  y_root  The  pointer  coordinates  relative  to  the  root  window  which  is  an  ancestor 
of  the  event  window.  If  the  pointer  was  on  a  different  screen,  these  ?~e 
zero. 

state  The  state  of  all  the  buttons  and  modifier  keys  just  before  the  event, 

represented   by  a  mask  of  the  button  and  modifier  key  symbols: 

ButtonlMask,  Button2Mask,  ButtonSMask,  Button4Mask, 
ButtonSMask,  ControlMask,  LockMask,  ModlMask,  Mod2- 
Mask, ModSMask, Mod4Mask,  ModSMask,  and  Shif  tMask. 

keycode  The  keycode  member  contains  a  server-dependent  code  for  the  key  that 

changed  state.  As  such,  it  should  be  translated  into  the  portable  symbol 
called  a  keysym  before  being  used.  It  can  also  be  converted  directly  into 
ASCII  with  XLookupString.  For  a  description  and  examples  of  how 
to  translate  keycodes,  see  Volume  One,  Section  9.1.1. 

Notes 

Remember  that  not  all  hardware  is  capable  of  generating  release  events  and  that  only  the  main 
keyboard  (a-z,  A-Z,  0-9),  Shift,  and  Control  keys  are  always  found. 

Keyboard  events  are  analogous  to  button  events,  though,  of  course,  there  are  many  more  keys 
than  buttons  and  the  keyboard  is  not  automatically  grabbed  between  press  and  release. 

All  the  structure  members  have  the  same  meaning  as  described  for  ButtonPress  and 
ButtonRelease  events,  except  that  button  is  replaced  by  keycode. 
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MapNotlfy,  UnmapNotify 


X 


•xmap,  xunmap — 


When  Generated 

The  X  server  generates  MapNotif y  and  UnmapNotify  events  when  a  window  changes  state 
from  unmapped  to  mapped  or  vice  versa. 

Select  With 

To  receive  these  events  on  a  single  window,  use  StructureNotifyMask  in  the  call  to 
XSelect  Input  for  the  window.  To  receive  these  events  for  all  children  of  a  particular 
parent,  specify  the  parent  window  ID  and  use  SubstructureNotif  yMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XMapEvent  xmap; 
XUnmapEvent  xunmap; 

}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial; 

Bool  send_event; 

Display  *display; 

Window  event; 

Window  window; 

Bool  override_redirect, 
}  XMapEvent; 

typedef  struct  { 

int  type; 

unsigned  long  serial; 

Bool  send_event; 

Display  *display; 

Window  event; 

Window  window; 

Bool  from_conf igure; 
}  XUnmapEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request  */ 
/*  Display  the  event  was  read  from  */ 


/*  boolean,  is  override  set  */ 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request  */ 
/*  Display  the  event  was  read  from  */ 


Event  Structure  Members 

event  The  window  that  selected  this  event 


The  window  that  was  just  mapped  or  unmapped. 
override_redirect  (XMapEvent  only) 

True  or  False.   The  value  of  the  override_redirect  attribute  of  the 
window  that  was  just  mapped. 
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(continued) 


MapNotify,  UnmapNotify 


f rom_conf igure  (XUnmapEvent  only) 

True  if  the  event  was  generated  as  a  result  of  a  resizing  of  the  window's  parent 
when  the  window  itself  had  a  win_gravity  of  UnmapGravity.  See  the 
description  of  the  win_gravity  attribute  in  Section  4.3.4  of  Volume  One, 
Xlib  Programming  Manual.  False  otherwise. 
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MappingNotify 


X 


•xmapping — 


When  Generated 

A  MappingNotify  event  is  sent  when  any  of  the  following  is  changed  by  another  client:  the 
mapping  between  physical  keyboard  keys  (keycodes)  and  keysyms,  the  mapping  between 
modifier  keys  and  logical  modifiers,  or  the  mapping  between  physical  and  logical  pointer 
buttons.  These  events  are  triggered  by  a  call  to  XSetModifierMapping  or  XSet- 
PointerMapping,  if  the  return  status  is  MappingSuccess,  or  by  any  call  to  XChange- 
Keyboa  rdMapping. 

This  event  type  should  not  be  confused  with  the  event  that  occurs  when  a  window  is  mapped; 
that  is  a  MapNotify  event  Nor  should  it  be  confused  with  the  KeymapNotify  event, 
which  reports  the  state  of  the  keyboard  as  a  mask  instead  of  as  a  keycode. 

Select  With 

The  X  server  sends  MappingNotify  events  to  all  clients.  It  is  never  selected  and  cannot  be 
masked  with  the  window  attributes. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XMappingEvent  xmapping; 
}  XEvent; 


/*  #  of  last  request  processed  by  server  */ 

/*  True  if  this  came  from  SendEvent  request  */ 

/*  Display  the  event  was  read  from  */ 

/*  unused  */ 

/*  one  of  MappingMapping,  MappingKeyboard, 

*  MappingPointer  */ 

/*  first  keycode  */ 

/*  range  of  change  with  f irst_keycode*/ 


Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial 
Bool  send_event; 
Display  *display; 
Window  window; 
int  request; 

int  f irst_keycode; 
int  count; 
}  XMappingEvent; 

Event  Structure  Members 

request  The  kind  of  mapping  change  that  occurred:  MappingModif  ier  for  a 

successful  XSetModifierMapping  (keyboard  Shift,  Lock,  Control, 
Meta  keys),  MappingKeyboard  for  a  successful  XChange- 
Keyboa rdMapping  (other  keys),  and  MappingPointer  for  a  suc 
cessful  XSetPointerMapping  (pointer  button  numbers). 

first_keycode  If  the  request  member  is  MappingKeyboard  or  Mapping- 
Modifier,  then  f  irst_keycode  indicates  the  first  in  a  range  of  key- 
codes  with  altered  mappings.  Otherwise,  it  is  not  set 
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xmapplng  (continued)  MappingNotify 

count  If  the    request    member   is   MappingKeyboard  or  Mapping- 

Modifier,  then  count  indicates  the  number  of  keycodes  with  altered 
mappings.  Otherwise,  it  is  not  set 

Notes 

If  the  request  member  is  MappingKeyboard,  clients  should  call  XRef reshKeyboard- 
Mapping. 

The  normal  response  to  a  request  member  of  MappingPointer  or  MappingModif  ier 
is  no  action.  This  is  because  the  clients  should  use  the  logical  mapping  of  the  buttons  and 
modifiers  to  allow  the  user  to  customize  the  keyboard  if  desired.  If  the  application  requires  a 
particular  mapping  regardless  of  the  user's  preferences,  it  should  call  XGetModif  ier- 
Mapping  or  XGetPointerMapping  to  find  out  about  the  new  mapping. 
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MapRequest  \ xm,pr.qu.«_ 

When  Generated 

A  MapRequest  event  occurs  when  the  functions  XMapRaised  and  XMapWindow  are 
called. 

This  event  differs  from  MapNot  if  y  in  that  it  delivers  the  parameters  of  the  request  before  it  is 
carried  out  This  gives  the  client  that  selects  this  event  (usually  the  window  manager)  the 
opportunity  to  revise  the  size  or  position  of  the  window  before  executing  the  map  request  itself 
or  to  deny  the  request  (MapNot  i  f  y  indicates  the  final  outcome  of  the  request) 

Select  With 

This  event  is  selected  by  specifying  the  window  ID  of  the  parent  of  the  receiving  window  with 
SubstructureRedirectMask.  (In  addition,  the  override_redirect  member  of  the 
XSetwindowAttributes  structure  for  the  specified  window  must  be  False.) 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XMapRequestEvent  xmaprequest; 
}  XEvent; 

Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 
Bool  send_event;       /*  True  if  this  came  from  SendEvent  request  */ 
Display  *display;     /*  Display  the  event  was  read  from  */ 
Window  parent; 
Window  window; 

}  XMapRequestEvent; 

Event  Structure  Members 

pa  rent          The  ID  of  the  parent  of  the  window  being  mapped. 
window          The  ID  of  the  window  being  mapped. 
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MotionNotify 


When  Generated 

A  MotionNotify  event  reports  that  the  user  moved  the  pointer  or  that  a  program  warped  the 
pointer  to  a  new  position  within  a  single  window. 

Select  With 

This  event  is  selected  with  ButtonMotionMask,  ButtonlMotionMask,  Button2- 
MotionMask,  ButtonSMotionMask,  Button4MotionMask,  ButtonSMotionMask, 
PointerMotionHintMask,  and  PointerMotionMask.  These  masks  determine  the  spe 
cific  conditions  under  which  the  event  is  generated. 

See  Section  8.3.3.3  of  Volume  One,  Xlib  Programming  Manual,  for  a  description  of  selecting 
button  events. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XMotionEvent  xmotion; 
}  XEvent; 


Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial, 
Bool  send_event; 
Display  *display; 
Window  window; 
Window  root; 
Window  subwindow; 
Time  time; 
int  x,  y; 

int  x_root,  y_root; 
unsigned  int  state; 
char  is_hint; 
Bool  same_screen; 
}  XMotionEvent; 


/*  of  event  */ 

/*  #  of  last  request  processed  by  server  */ 

/*  True  if  this  came  from  SendEvent  request  */ 

/*  Display  the  event  was  read  from  */ 

/*  event  window  it  is  reported  relative  to  */ 

/*  root  window  that  the  event  occurred  on  */ 

/*  child  window  */ 

/*  milliseconds  */ 

/*  pointer  coordinates  relative  to  receiving 

*  window  */ 

/*  coordinates  relative  to  root  */ 
/*  button  and  modifier  key  mask  */ 
/*  is  this  a  motion  hint  */ 
/*  same  screen  flag  */ 


typedef  XMotionEvent  XPointerMovedEvent; 


Event  Structure  Members 

subwindow  If  the  source  window  is  the  child  of  the  receiving  window,  then  the 

subwindow  member  is  set  to  the  ID  of  that  child. 


time 


The  server  time  when  the  button  event  occurred,  in  milliseconds.  Time 
is  declared  as  unsigned  long,  so  it  wraps  around  when  it  reaches  the 
maximum  value  of  a  32-bit  number  (every  49.7  days). 
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MotionNotify 


(continued) 


xmotion 


x,  y  if  the  receiving  window  is  on  the  same  screen  as  the  root  window  speci 

fied  by  root,  then  x  and  y  are  the  pointer  coordinates  relative  to  the 
receiving  window's  origin.  Otherwise,  x  and  y  are  zero. 

When  active  button  grabs  and  pointer  grabs  are  in  effect  (see  Volume 
One,  Section  9.4),  the  coordinates  relative  to  the  receiving  window  may 
not  be  within  the  window  (they  may  be  negative  or  greater  than  window 
height  or  width). 

x_root,  y_root  The  pointer  coordinates  relative  to  the  root  window  which  is  an  ancestor 
of  the  event  window.  If  the  pointer  was  on  a  different  screen,  these  are 
zero. 

state  The  state  of  all  the  buttons  and  modifier  keys  just  before  the  event, 

represented   by  a  mask  of  the  button  and  modifier  key  symbols: 

ButtonlMask,  Button2Mask,  ButtonSMask,  Button4Mask, 
ButtonSMask,  ControlMask,  LockMask,  ModlMask,  Mod2- 
Mask,  ModSMask,  Mod4Mask,  ModSMask,  and  Shif  tMask. 

is_hint  Either  the  constant  Notif yNormal  or  Notif yHint.  Notif yHint 

indicates  that  the  PointerMotionHintMask  was  selected.  In  this 
case,  just  one  event  is  sent  when  the  mouse  moves,  and  the  current  posi 
tion  can  be  found  by  calling  XQueryPo inter  or  by  examining  the 
motion  history  buffer  with  XGetMotionEvents,  if  a  motion  history 
buffer  is  available  on  the  server.  Not  if  yNormal  indicates  that  the 
event  is  real,  but  it  may  not  be  up  to  date,  since  there  may  be  many  more 
later  motion  events  on  the  queue. 

same_screen  Indicates  whether  the  pointer  is  currently  on  the  same  screen  as  this  win 
dow.  This  is  always  True  unless  the  pointer  was  actively  grabbed 
before  the  automatic  grab  could  take  place. 

Notes 

If  the  processing  you  have  to  do  for  every  motion  event  is  fast,  you  can  probably  handle  all  of 
them  without  requiring  motion  hints.  However,  if  you  have  extensive  processing  to  do  for  each 
one,  you  might  be  better  off  using  the  hints  and  calling  XQueryPointer  or  using  the  history 
buffer  if  it  exists.  XQueryPointer  is  a  round-trip  request,  so  it  can  be  slow. 

EnterNotify  and  LeaveNotify  events  are  generated  instead  of  Mot ionE vents  if  the 
pointer  starts  and  stops  in  different  windows. 
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PropertyNotify 


When  Generated 

A  PropertyNotify  event  indicates  that  a  property  of  a  window  has  changed  or  been 
deleted.  This  event  can  also  be  used  to  get  the  current  server  time  (by  appending  zero-length 
data  to  a  property).  PropertyNotify  events  are  generated  by  XChangeProperty, 
XDeleteProperty,  XGetWindowProperty,  or  XRotateWindowProperties. 

Select  With 

This  event  is  selected  with  PropertyChangeMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XPropertyEvent  xproperty; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial; 

Bool  send_event; 

Display  *display; 

Window  window; 

Atom  atom; 

Time  time; 

int  state; 
}  XPropertyEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request  */ 
/*  Display  the  event  was  read  from  */ 


/*  property  NewValue,  property  Deleted  */ 


Event  Structure  Members 

window         The  window  whose  property  was  changed,  not  the  window  that  selected  the 
event 

atom  The  property  that  was  changed. 

state  Either  PropertyNewValue  or  PropertyDelete.   Whether  the  property 

was  changed  to  a  new  value  or  deleted. 

t  ime  The  t  ime  member  specifies  the  server  time  when  the  property  was  changed. 
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ReparentNotify 


X 


•xreparent — 


When  Generated 

A  ReparentNotify  event  reports  when  a  client  successfully  reparents  a  window. 

Select  With 

This  event  is  selected  with  SubstructureNotif  yMask  by  specifying  the  window  ID  of  the 
old  or  the  new  parent  window  or  with  StructureNotifyMask  by  specifying  the  window 
ID. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XReparentEvent  xreparent; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial 

Bool  send_event; 

Display  *display; 

Window  event; 

Window  window; 

Window  parent; 

int  x,  y; 

Bool  override_redirect; 
}  XReparentEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request 
/*  Display  the  event  was  read  from  */ 


Event  Structure  Members 

window  The  window  whose  parent  window  was  changed. 

pa  rent  The  new  parent  of  the  window. 

x,  y  The  coordinates  of  the  upper-left  pixel  of  the  window's  border  rela 

tive  to  the  new  parent  window's  origin. 

override_redirect  The  override_redirect  attribute  of  the  reparented  window.  If 
True,  it  indicates  that  the  client  wants  this  window  to  be  immune 
to  meddling  by  the  window  manager.  Window  managers  normally 
should  not  have  reparented  this  window  to  begin  with. 
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— xresizerequest- 


ResizeRequest 


When  Generated 

A  ResizeRequest  event  reports  another  client's  attempt  to  change  the  size  of  a  window. 
The  X  server  generates  this  event  type  when  another  client  calls  XConf  igurewindow, 
XMoveResizeWindow,  or  XResizeWindow.  If  this  event  type  is  selected,  the  window  is 
not  resized.  This  gives  the  client  that  selects  this  event  (usually  the  window  manager)  the 
opportunity  to  revise  the  new  size  of  the  window  before  executing  the  resize  request  or  to  deny 
the  request  itself. 

Select  With 

To  receive  this  event  type,  specify  a  window  ID  and  pass  ResizeRedirectMask  as  part  of 
the  event_mask  argument  to  XSelectlnput.  Only  one  client  can  select  this  event  on  a 
particular  window.  When  selected,  this  event  is  triggered  instead  of  resizing  the  window. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XResizeRequestEvent  xresizerequest ; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  *display; 

Window  window; 

int  width,  height; 
}  XResizeRequestEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request  */ 
/*  Display  the  event  was  read  from  */ 


Event  Structure  Members 

window  The  window  whose  size  another  client  attempted  to  change. 

width,  height        The  requested  size  of  the  window,  not  including  its  border. 
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SelectionClear  V. 

v xselectlonclear  — 

When  Generated 

A  SelectionClear  event  reports  to  the  current  owner  of  a  selection  that  a  new  owner  is 
being  defined. 

Select  With 

This  event  is  not  selected.  It  is  sent  to  the  previous  selection  owner  when  another  client  calls 
XSetSelectionOwner  for  the  same  selection. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XSelectionClearEvent  xselectionclear; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;       /*  True  if  this  came  from  SendEvent  request  */ 

Display  'display;     /*  Display  the  event  was  read  from  */ 

Window  window; 

Atom  selection; 

Time  time; 
}  XSelectionClearEvent; 

Event  Structure  Members 

window  The  window  that  is  receiving  the  event  and  losing  the  selection. 

selection         The  selection  atom  specifying  the  selection  that  is  changing  ownership, 
t  ime  The  last-change  time  recorded  for  the  selection. 
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—  xselection- 


SelectionNotify 


When  Generated 

A  SelectionNotify  event  is  sent  only  by  clients,  not  by  the  server,  by  calling  xSend- 
Event.  The  owner  of  a  selection  sends  this  event  to  a  requestor  (a  client  that  calls 
XConvertSelection  for  a  given  property)  when  a  selection  has  been  converted  and  stored 
as  a  property  or  when  a  selection  conversion  could  not  be  performed  (indicated  with  property 

None). 

Select  With 

There  is  no  event  mask  for  SelectionNotify  events,  and  they  are  not  selected  with 
XSelect Input.  Instead  XSendEvent  directs  the  event  to  a  specific  window,  which  is 
given  as  a  window  ID:  PointerWindow,  which  identifies  the  window  the  pointer  is  in,  or 
inputFocus,  which  identifies  the  focus  window. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XSelectionEvent  xselection; 
}  XEvent; 


Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial, 

Bool  send_event; 

Display  ^display; 

Window  requestor; 

Atom  selection; 

Atom  target; 

Atom  property; 

Time  time; 
}  XSelectionEvent; 


/*  #  of  last  request  processed  by  server  */ 
/*  True  if  this  came  from  SendEvent  request 
/*  Display  the  event  was  read  from  */ 


/*  Atom  or  None  */ 


Event  Structure  Members 

The  members  of  this  structure  have  the  values  specified  in  the  XConvertSelection  call 
that  triggers  the  selection  owner  to  send  this  event,  except  that  the  property  member  either 
will  return  the  atom  specifying  a  property  on  the  requestor  window  with  the  data  type  specified 
in  target  or  will  return  None,  which  indicates  that  the  data  could  not  be  converted  into  the 
target  type. 
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SelectionRequest  \ 


•  xse  lectionrequest — 


When  Generated 

A  SelectionRequest  event  is  sent  to  the  owner  of  a  selection  when  another  client  requests 
the  selection  by  calling  xConvert  Select  ion. 

Select  With 

There  is  no  event  mask  for  SelectionRequest  events,  and  they  are  not  selected  with 

XSelectlnput. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XSelectionRequestEvent  xselectionrequest; 
}  XEvent; 

Event  Structure 

typedef  struct  { 

int  type; 

unsigned  long  serial;  /*  #  of  last  request  processed  by  server  */ 

Bool  send_event;       /*  True  if  this  came  from  SendEvent  request  */ 

Display  *display;     /*  Display  the  event  was  read  from  */ 

Window  owner; 

Window  requestor; 

Atom  selection; 

Atom  target; 

Atom  property; 

Time  time; 
}  XSelectionRequestEvent; 

Event  Structure  Members 

The  members  of  this  structure  have  the  values  specified  in  the  XConvert  Select  ion  call 
that  triggers  this  event 

The  owner  should  convert  the  selection  based  on  the  specified  target  type,  if  possible.  If  a 
property  is  specified,  the  owner  should  store  the  result  as  that  property  on  the  requestor  window 
and  then  send  a  SelectionNotif y  event  to  the  requestor  by  calling  xSendEvent.  If  the 
selection  cannot  be  converted  as  requested,  the  owner  should  send  a  SelectionNotify 
event  with  property  set  to  the  constant  None. 
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—xvisibility- 


VisibilityNotify 


When  Generated 

A  VisibilityNotify  event  reports  any  change  in  the  visibility  of  the  specified  window. 
This  event  type  is  never  generated  on  windows  whose  class  is  inputOnly.  All  of  the  win 
dow's  subwindows  are  ignored  when  calculating  the  visibility  of  the  window. 

Select  With 

This  event  is  selected  with  visibilityChangeMask. 

XEvent  Structure  Name 

typedef  union  _XEvent  { 

XVisibilityEvent  xvisibility; 
}  XEvent; 


Event  Structure 

typedef  struct  { 
int  type; 

unsigned  long  serial, 
Bool  send_event; 
Display  ^display; 
Window  window; 
int  state; 


/*  #  of  last  request  processed  by  server  */ 

/*  True  if  this  came  from  SendEvent  request 

/*  Display  the  event  was  read  from  */ 

/*  VisibilityObscured, 

*  VisibilityPartiallyObscured, 

*  VisibilityUnobscured*/ 


}  XVisibilityEvent; 


Event  Structure  Members 

state  A  symbol  indicating  the  final  visibility  status  of  the  window:   Visibility- 

Obscured,      VisibilityPartiallyObscured,      or     Visibility 
Unobscured. 

Notes 

Table  E-5  lists  the  transitions  that  generate  VisibilityNotify  events  and  the  correspond 
ing  state  member  of  the  XVisibilityEvent  structure. 
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VisibilityNotify 


(continued) 


xvisibility 


Table  E-5.  State  Element  of  the  XVisibilityEvent  Structure 

Visibility  Status  Before        Visibility  Status  After          State  Member 


Partially  obscured, 
fully  obscured, 
or  not  viewable 

Viewable  and 
completely  unobscured, 
or  not  viewable 

Viewable  and 
completely  unobscured, 
or  viewable  and 
partially  obscured, 
or  not  viewable 


Viewable  and 
completely  unobscured 

Viewable  and 
partially  obscured 

Viewable  and 
partially  obscured 


VisibilityUnobscured 


VisibilityPartially- 
Obscured 


VisibilityPartially- 
Obscured 
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Structure  Reference 


This  appendix  summarizes  the  contents  of  the  include  files  for  Xlib,  and  presents  each  struc 
ture  in  alphabetical  order. 


F.1   Description  of  Header  Files 

All  include  files  are  normally  located  in  lusrlindudelXl  1 .  All  Xlib  programs  require 
<XU/Xlib.h>,  which  includes  <Xll/X.h>.  <Xll/Xlib.h>  contains  most  of  the  structure  dec 
larations,  while  <Xll/X.h>  contains  most  of  the  defined  constants.  Virtually  all  programs 
will  also  require  <XlllXutil.h>,  which  include  structure  types  and  declarations  applicable  to 
window  manager  hints,  colors,  visuals,  regions,  standard  geometry  strings,  and  images. 

Here  is  a  summary  of  the  contents  of  the  include  files: 

<XlllXlib.h>  structure  declarations  for  core  Xlib  functions. 

<XlllX.h>  constant  definitions  for  Xlib  functions. 

<Xll/Xutil.h>  additional  structure  types  and  constant  definitions  for  miscellaneous 

Xlib  functions. 

<XlllXatom.h>  the  predefined  atoms  for  properties,  types,  and  font  characteristics. 

<Xll/cursorfont.h>        the  constants  used  to  select  a  cursor  shape  from  the  standard  cursor 
font. 

<Xlllkeysym.h>  predefined  key  symbols  corresponding  to  keycodes.    It  includes 

<Xll/keysymdef.h>. 

<Xll/Xresource.h>        resource  manager  structure  definitions  and  function  declarations. 
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F.2  Resource  Types 

The  following  types  are  defined  in  <XU/X.h>: 

unsigned  long  XID 

XID  Colormap 

XID  Cursor 

XID  Drawable 

XID  Font 

XID  GContext 

XID  KeySym 

XID  Pixmap 

XID  Window 

unsigned  long  Atom 

unsigned  char  KeyCode 

unsigned  long  Mask 

unsigned  long  Time 

unsigned  long  VisuallD 


F.3  Structure  Definitions 

This  section  lists  all  public  Xlib  structure  definitions  in  XI  ib .  h  and  Xutil .  h,  in  alphabet 
ical  order,  except  the  event  structures,  which  are  listed  on  the  reference  page  for  each  event 
in  Appendix  E,  Event  Reference. 

Before  each  structure  is  a  description  of  what  the  structure  is  used  for  and  a  list  of  the  Xlib 
routines  that  use  the  structure. 


F.3.1    XArc 

XArc  specifies  the  bounding  box  for  an  arc  and  two  angles  indicating  the  extent  of  the  arc 
within  the  box.  A  list  of  these  structures  is  used  in  XDrawArcs  and  XFillArcs. 

typedef  struct  { 

short  x,  y; 

unsigned  short  width,  height; 

short  anglel,  angle2; 
}  XArc; 
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XChar2b 

XChar2b  specifies  a  character  in  a  two-byte  font  A  list  of  structures  of  this  type  is  an  argu 
ment  to  XDrawImageSt  ringl  6,  XDrawStringl  6,  XDrawText  1 6,  XQueryText- 
Extentsl6,  XTextExtentsl6,  and  XTextWidthl6.  The  only  two-byte  font  cur 
rently  available  is  Kanji  (Japanese). 

typedef  struct  {  /*  normal  16  bit  characters  are  two  bytes  */ 

unsigned  char  bytel; 

unsigned  char  byte2; 
}  XChar2b; 


F.3.3   XCharStruct 

XCharStruct  describes  the  metrics  of  a  single  character  in  a  font  or  the  overall  character 
istics  of  a  font  This  structure  is  the  type  of  several  of  members  of  XFont Struct  and  is 
used  to  return  the  overall  characteristics  of  a  string  in  XQueryTextExtents*  and 
XTextExtents*. 

typedef  struct  { 

short  Ibearing;  /*  origin  to  left  edge  of  raster  */ 

short  rbearing;  /*  origin  to  right  edge  of  raster  */ 

short  width;  /*  advance  to  next  char's  origin  */ 

short  ascent;  /*  baseline  to  top  edge  of  raster  */ 

short  descent;  /*  baseline  to  bottom  edge  of  raster  *, 

unsigned  short  attributes;  /*  per  char  flags  (not  predefined)  */ 

}  XCharStruct; 


F.3.4   XCIassHint 

XClassHint  is  used  to  set  or  get  the  XA_WM_CLASS_HINT  property  for  an  application's 
top-level  window,  as  arguments  toXSetClassHint  or  XGetClassHint. 

typedef    struct    { 

char    *res_name; 

char   *res_class; 
}    XClassHint; 


F.3.5   XColor 

XColor  describes  a  single  colorcell.  This  structure  is  used  to  specify  and  return  the  pixel 
value  and  RGB  values  for  a  colorcell.  The  flags  indicate  which  of  the  RGB  values  should  be 
changed  when  used  in  XStoreColors,  XAllocNamedColor,  or  XAllocColor. 
Also  used  in  XCreateGlyphCursor,  XCreatePixmapCursor,  XLookupColor, 
XParseColor,  XQueryColor,  XQueryColors,  and  XRecolorCursor. 
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typedef  struct  { 

unsigned  long  pixel; 

unsigned  short  red,  green,  blue; 

char  flags; 

char  pad; 
}  XColor; 


DoRed,  DoGreen,  DoBlue  */ 


F.3.6    XComposeStatus 


XCoxnposeStatus  describes  the  current  state  of  a  multikey  character  sequence.  Used  in 
calling  XLookupSt ring.  This  processing  is  not  implemented  in  the  MIT  sample  servers. 


typedef  struct  _XComposeStatus  { 

char  *compose_ptr; 

int  chars  matched; 
}  XComposeStatus; 


/*  state  table  pointer  */ 
/*  match  state  */ 


F.3.7  XExtCodes 


XExtCodes  is  a  structure  used  by  the  extension  mechanism.  This  structure  is  returned  by 
xinitExtension  which  is  not  a  standard  Xlib  routine  but  should  be  called  within  the 
extension  code.  Its  contents  are  not  normally  accessible  to  the  application. 

typedef  struct  { 

int  extension; 

int  ma jor_opcode; 

int  first_event; 

int  first_error; 
}  XExtCodes; 


/*  public  to  extension,  cannot  be  changed  */ 

/*  extension  number  */ 

/*  major  opcode  assigned  by  server  */ 

/*  first  event  number  for  the  extension  */ 

/*  first  error  number  for  the  extension  */ 


F.3.8  XExtData 


XExtData  provides  a  way  for  extensions  to  attach  private  data  to  the  existing  structure 
types  GC,  visual,  Screen,  Display,  and  XFontStruct.  This  structure  is  not  used 
in  normal  Xlib  programming. 


typedef  struct  _XExtData  { 

int  number; 

struct  _XExtData  *next; 

int  (*free_private) {) ; 

char  *private_data; 
}  XExtData; 


/*  number  returned  by  XRegisterExtension  */ 

/*  next  item  on  list  of  data  for  structure  */ 

/*  called  to  free  private  storage  */ 

/*  data  private  to  this  extension  */ 
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F.3.9   XFontProp 


XFontProp  is  used  in  XFont Struct.  This  structure  allows  the  application  to  find  out 
the  names  of  additional  font  properties  beyond  the  predefined  set,  so  that  they  too  can  be 
accessed  with  XGet  Font  Property.  This  structure  is  not  used  as  an  argument  or  return 
value  for  any  core  Xlib  function. 

typedef  struct  { 

Atom  name; 

unsigned    long    card32; 
}    XFontProp; 


F.3.10   XFontStruct 


XFont  Struct  specifies  metric  information  for  an  entire  font  This  structure  is  filled  with 
the  XLoadQueryFont  and  XQueryFont  routines.  ListFontsWithlnf  o  also  fills  it 
but  with  metric  information  for  the  entire  font  only,  not  for  each  character.  A  pointer  to  this 
structure  is  used  in  the  routines  XFreeFont,  XFreeFontlnf o,  XGetFontProp, 
XTextExtents*,  and  XTextwidth*. 


typedef  struct  { 

XExtData  *ext_data;  /* 

Font  fid;  /* 

unsigned  direction;  /* 
unsigned  min_char_or_byte2;  /* 
unsigned  max_char_or_byte2;  /* 

unsigned  min_bytel;  /* 

unsigned  max_bytel;  /* 

Bool  all_chars_exist;  /* 

unsigned  default_char;  /* 

int  n_properties;  /* 

XFontProp  *properties;  /* 

XCharStruct  min_bounds;  /* 

XCharStruct  max_bounds;  /* 

XCharStruct  *per_char;  /* 

int  ascent;  /* 

int  descent;  /* 

}  XFontStruct; 


hook  for  extension  to  hang  data  */ 

font  ID  for  this  font  */ 

direction  the  font  is  painted  */ 

first  character  */ 

last  character  */ 

first  row  that  exists  */ 

last  row  that  exists  */ 

flag  if  all  characters  have  nonzero  size*/ 

char  to  print  for  undefined  character  */ 

how  many  properties  there  are  */ 

pointer  to  array  of  additional  properties*/ 

minimum  bounds  over  all  existing  char*/ 

maximum  bounds  over  all  existing  char*/ 

first_char  to  last_char  information  */ 

logical  extent  above  baseline  for  spacing  */ 

logical  descent  below  baseline  for  spacing  */ 


F.3.11    XGCValues 


XGCValues  is  used  to  set  or  change  members  of  the  GC  by  the  routines  XGreateGC  and 
XChangeGC. 


typedef  struct  { 
int  function; 
unsigned  long  plane_mask; 
unsigned  long  foreground; 


/*  logical  operation  */ 

/*  plane  mask  */ 

/*  foreground  pixel  */ 
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unsigned  long  background; 
int  line_width; 
int  line_style; 
int  cap_style; 
int  join_style; 
int  fill_style; 
int  fill_rule; 
int  arc  mode; 
Pixmap  tile; 
Pixmap  stipple; 
int  ts_x_origin; 
int  ts_y_origin; 
Font  font; 
int  subwindow_mode; 
Bool  graphics_exposures; 
int  clip_x_origin; 
int  clip_y_origin; 
Pixmap  clip_mask; 
int  dash_offset; 
char  dashes; 
XGCValue.; 


/*  background  pixel  */ 

/*  line  width  */ 

/*  LineSolid,  LineOnOf fDash,  LineDoubleDash  */ 

/*  CapNotLast,  CapButt,  CapRound,  CapPro jecting  */ 

/*  JoinMiter,  JoinRound,  JoinBevel  */ 

/*  FillSolid,  FillTiled,  FillStippled  */ 

/*  EvenOddRule,  WindingRule  */ 

/*  ArcPieSlice,  ArcChord  */ 

/*  tile  pixmap  for  tiling  operations  */ 

/*  stipple  1  plane  pixmap  for  stippling  */ 

/*  offset  for  tile  or  stipple  operations  */ 

/*  default  text  font  for  text  operations  */ 
/*  ClipByChildren,  Includelnferiors  */ 
/*  Boolean,  should  exposures  be  generated  */ 
/*  origin  for  clipping  */ 

/*  bitmap  clipping;  other  calls  for  rects  */ 
/*  patterned/dashed  line  information  */ 


F.3.12   XHostAddress 


XHostAddress  specifies  the  address  of  a  host  machine  that  is  to  be  added  or  removed  from 
the  host  access  list  for  a  server.  Used  in  XAddHost,  XAddHosts,  XListHosts, 
XRemoveHost,  and  XRemoveHosts. 


typedef  struct  { 
int  family; 
int  length; 
char  *address; 

}  XHostAddress; 


/*  for  example  FAMILY_INTERNET  */ 
/*  length  of  address,  in  bytes  */ 
/*  pointer  to  where  to  find  the  bytes  */ 


F.3.13  XlconSize 


XlconSize  is  Used  to  set  or  read  the  XA_WM_ICON  SIZE  property.  This  i 

XSetIconSizes  «*'"«  by  each  application 


typedef  struct  { 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 
}  XlconSize; 
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F.3.14   Xlmage 


Xlmage  describes  an  area  of  the  screen;  is  used  in  XCreatelmage,  XDestroylmage, 
XGetPixel,  XPutPixel,  XSublmage,  XAddPixel,  XGetlmage,  XGetSub- 
Image,  and  XPut  Image. 


typedef  struct  _XImage  { 

int  width,  height; 

int  xoffset; 

int  format; 

char  *data; 

int  byte_order; 

int  bitmap_unit; 

int  bitmap_bit_order; 

int  bitmap_pad; 

int  depth; 

int  bytes_per_line; 

int  bits_per_pixel; 

unsigned  long  red_mask; 

unsigned  long  green_mask; 

unsigned  long  blue_mask; 

char  *obdata; 

struct  funcs  { 

struct  _XImage  * (*create_image) () 
int  (*destroy_image) {) ; 
unsigned  long  (*get_pixel) ( ) ; 
int  (*put_pixel) (); 
struct  _XImage  * (*sub_image) () ; 
int  (*add_pixel) {); 

}  f; 
}  Xlmage; 


/*  size  of  image  */ 

/*  number  of  pixels  offset  in  X  direction  */ 

/*  XYBitmap,  XYPixmap,  ZPixmap  */ 

/*  pointer  to  image  data  */ 

/*  data  byte  order,  LSBFirst,  MSBFirst  */ 

/*  quant,  of  scan  line  8,  16,  32  */ 

/*  LSBFirst,  MSBFirst  */ 

/*  8,  16,  32  either  XY  or  ZPixmap  */ 

/*  depth  of  image  */ 

/*  accelerator  to  next  line  */ 

/*  bits  per  pixel  (ZPixmap)  */ 

/*  bits  in  z  arrangement  */ 


/*  hook  for  the  object  routines  to  hang  on  */ 
/*  image  manipulation  routines  */ 


F.3.15   XKeyboardControl 

XKeyboardControl    is   used   to   set   user  preferences    with   XChangeKeyboard- 
Control. 

typedef  struct  { 

int  key_click_percent; 

int  bell_percent; 

int  bell_pitch; 

int  bell_duration; 

int  led; 

int  led_mode; 

int  key; 

int  auto  repeat  mode; 


AutoRepeatModeOn,  AutoRepeatModeOf f , 
AutoRepeatModeDefault  */ 


}  XKeyboardControl; 
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F.3.16   XKeyboardState 

XKeyboardState  is  used  to  return  the  current  settings  of  user  preferences  with  XGet 
KeyboardControl. 


typedef  struct  { 

int  key_click_percent; 

int  bell_percent; 

unsigned  int  bell_pitch,  bell_duration; 

unsigned  long  led_mask; 

int  global_auto_repeat; 

char  auto_repeats [32] ; 
}  XKeyboardState; 


F.3.17   XModifierKeymap 

XModif  ierKeymap  specifies  which  physical  keys  are  mapped  to  modifier  functions.  This 
structure  is  returned  by  XGetModif  ierMapping  and  is  an  argument  to  XDelete- 
Modif iermapEntry,  XFreeModif iermap,  XInsertModif iermapEntry, 
XNewModif  iermap,  and  XSetModif  ierMapping. 

typedef  struct  { 

int  maxjceypermod;  /*  server's  max  f  of  keys  per  modifier  */ 

KeyCode  *modif iermap;  /*  an  8  by  max_keypermod  array  of  modifiers 

}  XModifi«rK«ym*p; 


F.3.18   XPixmapFormatValues 

XPixmapFonnatValues  describes  one  pixmap  format  that  is  supported  on  the  server.  A 
list  of  these  structures  is  returned  by  XListPixmapFormat  s. 

typedef  struct  { 

int  depth; 

int  bits_per_pixel; 

int  scanline_pad; 
}  XPixmapFormatValues; 


F.3.19   XPoint 

XPoint  specifies  the  coordinates  of  a  point.   Used  in  XDrawPoints,  XDrawLines 
XFillPolygon,  and  XPolygonRegion. 

typedef   struct    { 

short    x,    y; 
}    XPoint; 


CCO 
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F.3.20   XRectangle 


XRectangle  specifies  a  rectangle.  Used  in  XClipBox,  XDrawRectangles,  XFill- 
Rectangles,  XSetClipRectangles,  and  XUnionRectWithRegion. 

typedef    struct    { 

short   x,    y; 

unsigned   short   width,    height; 
}    XRectangle; 


F.3.21    XSegment 


XSegment  specifies  two  points.  Used  in  XDrawSegments. 


typedef  struct  { 

short  xl,  yl,  x2,  y2; 
}  XSegment; 


F.3.22  XSetWIndowAttributes 


XSetwindowAttributes  contains  all  the  attributes  that  can  be  set  without  window  man 
ager  intervention.  Used  in  XChangeWindowAttributes  and  XCreateWindow. 

typedef  struct  { 

Pixmap  background_pixmap;     /' 
unsigned  long  background_pixel; 


Pixmap  border_pixmap;  /i 

unsigned  long  border_pixel;  /i 

int  bit_gravity;  /i 

int  win_gravity;  /i 

int  backing_store;  /i 
unsigned  long  backing_planes; /i 

unsigned  long  backing_pixel;  /i 

Bool  save_under;  /i 

long  event  mask;  /i 

long  do_not_propagate_mask;  /i 

Bool  override_redirect;  /i 

Colormap  colormap;  /1 

Cursor  cursor;  /j 
}  XSetwindowAttributes; 


background  or  None  or  ParentRelative  */ 
'*  background  pixel  */ 
border  of  the  window  */ 
border  pixel  value  */ 
one  of  bit  gravity  values  */ 
one  of  the  window  gravity  values  */ 
NotUseful,  WhenMapped,  Always  */ 
planes  to  be  preserved  if  possible  */ 
value  to  use  in  restoring  planes  */ 
should  bits  under  be  saved?  (popups)  */ 
set  of  events  that  should  be  saved  */ 
set  of  events  that  should  not  */ 
propagate  */ 

Boolean  value  for  override-redirect  */ 
colormap  to  be  associated  with  window  */ 
cursor  to  be  displayed  (or  None)  */ 
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F.3.23   XSizeHints 


XSizeHints  describes  a  range  of  preferred  sizes  and  aspect  ratios.  Used  to  set  the 
XA_WM_NORMAL_HINTS  and  XA_WM_ZOOM_HINTS  properties  for  the  window  manager  with 
XSetStandardProperties,  XSetNormalHints,  XSetSizeHints,  or  XSet- 
ZoomHints  in  R3,  and  XSetWMProperties,  XSetWMNormalHints,  and  XSet- 
WMSizeHints  in  R4.  Also  used  in  reading  these  properties  with  XGetNormalHints, 
XGetSizeHints,  or  XGetZoomHints  in  R3,  and  XGetWMNormalHints  and 
XGetWMSizeHints. 

typedef  struct  { 

long  flags;  /*  marks  defined  fields  in  structure  */ 

int  x,  y;  /*  obsolete  in  R4  */ 

int  width,  height;  /*  obsolete  in  R4  */ 

int  min_width,  min_height; 

int  max_width,  max_height; 

int  width_inc,  height_inc; 

struct  { 

int  x;  /*  numerator  */ 

int  y;  /*  denominator  */ 

}  min_aspect,  max_aspect; 

int  base_width,  base_height;       /*  Added  in  R4  */ 
int  win_gravity;  /*  Added  in  R4  */ 

}  XSizeHints; 


F.3.24   XStandardColormap 

XStandardColormap  describes  a  standard  colormap,  giving  its  ID  and  its  color  character 
istics.  This  is  the  format  of  the  standard  colormap  properties  set  on  the  root  window  which 
can  be  changed  with  XSetRGBColormaps  (XSetStandardProperties  in  R3)  and 
read  with  XGetRGBColormaps  (XGetStandardProperties  in  R3). 

typedef  struct  { 

Colormap  colormap; 
unsigned  long  red_max; 
unsigned  long  red  mult; 
unsigned  long  green_max; 
unsigned  long  green_mult; 
unsigned  long  blue_max; 
unsigned  long  blue_mult; 
unsigned  long  base_pixel; 

ra"mi£'ualid;  '*  added  in  R4  *' 

/*    added    in    R4    */ 
}    XStandardColormap; 
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XTextltem 


XTextltem  describes  a  string,  the  font  to  print  it  in,  and  the  horizontal  offset  from  the  pre 
vious  string  drawn  or  from  the  location  specified  by  the  drawing  command.  Used  in 
XDrawText. 


typedef  struct  { 

char  *chars; 

int  nchars; 

int  delta; 

Font  font; 
}  XTextltem; 


/*  pointer  to  string  */ 

/*  number  of  characters  */ 

/*  delta  between  strings  */ 

/*  font  to  print  it  in,  None  don't  change  */ 


F.3.26    XTextltem16 


XTextlteml6  describes  a  string  in  a  two-byte  font,  the  font  to  print  it  in,  and  the  horizontal 
offset  from  the  previous  string  drawn  or  from  the  location  specified  by  the  drawing  com 
mand.  Used  in  XDrawText  16. 


typedef  struct  { 

XChar2b  *chars; 

int  nchars; 

int  delta; 

Font  font; 
}  XTextltemlS; 


/*  two-byte  characters  */ 

/*  number  of  characters  */ 

/*  delta  between  strings  */ 

/*  font  to  print  it  in.  None  don't  change  */ 


F.3.27   XTextProperty 


XTextProperty  holds  the  information  necessary  to  write  or  read  a  TEXT  property,  which 
contains  a  list  of  strings.  This  structure  is  used  by  many  of  the  R4  routines  that  write  and 
read  window  manager  hints  that  are  in  string  format.  The  purpose  of  this  structure  is  to  allow 
these  properties  to  be  processed  in  non-european  languages  where  more  than  8  bits  might  be 
needed.  These  structures  are  also  used  in  XGetTextProperty,  XSetTextProperty, 
XStringListToTextProperty,  and  XTextPropertyToStringList. 


typedef  struct  { 

unsigned  char  *value; 

Atom  encoding; 

int  format; 

unsigned  long  nitems; 
}  XTextProperty; 


/*  same  as  Property  routines  */ 

/*  prop  type  */ 

/*  prop  data  format:  8,  16,  or  32  */ 

/*  number  of  data  items  in  value  */ 
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F.3.28   XTimeCoord 


XTineCoord  specifies  a  time  and  position  pair,  for  use  in  tracking  the  pointer  with  XGet 
MotionEvents.  This  routine  is  not  supported  on  all  systems. 


typedef  struct  { 
Time  time; 
short  x,  y; 

}  XTimaCoord; 


F.3.29   XVisuallnfo 


XVisuallnfo  contains  all  the  information  about  a  particular  visual.  It  is  used  in  XGet- 
visuallnfo  and  XMatchVisuallnfo  to  specify  the  desired  visual  type.  The 
visual  member  of  XVisuallnfo  is  used  for  the  visual  argument  of  XCreate- 
Colormap  or  XCreateWindow. 


typedef  struct  { 

Visual  *visual; 

VisuallD  visualid; 

int  screen; 

unsigned  int  depth; 

int  class; 

unsigned  long  red_mask; 

unsigned  long  green_mask; 

unsigned  long  blue_mask; 

int  colormap_size; 

int  bits_per_rgb; 
}  XVisuallnfo; 


F.3.30   XWindowAttributes 

XWindowAttributes  describes  the  complete  set  of  window  attributes,  including  those 
that  cannot  be  set  without  window  manager  interaction.  This  structure  is  returned  by  XGet- 

WindowAttributes.     It  is    not    used    by    XChangeWindowAttributes     or 
XCreateWindow. 

typedef  struct  { 

int  x,  y;  /*  location  of  window  */ 

int  width,  height;  /*  width  and  height  of  window  */ 

int  border_width;  /*  border  width  of  window  */ 

int  depth;  /*  depth  of  window  */ 

Visual  *visual;  /*  the  associated  visual  structure  */ 

Window  root;  /*  root  of  screen  containing  window  */ 

int  class;  /*  InputOutput,  InputOnly*/ 

int  bit_gravity;  /*  one  of  bit  gravity  values  */ 

int  win_gravity;  /*  one  of  the  window  gravity  values  */ 

int  backing_store;  /*  NotUseful,  WhenMapped,  Always  */ 
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unsigned  long  backing_planes; 
unsigned  long  backing_pixel; 
Bool  save_under; 
Colormap  colormap; 
Bool  map_installed; 
int  map_state; 
long  all_event_masks; 
long  your_event_mask; 
long  do_not_propagate_mask; 
Bool  override_redirect; 
Screen  *screen; 
XWindowAtt ributes ; 


/*  planes  to  be  preserved  if  possible  */ 

/*  value  to  be  used  when  restoring  planes  */ 

/*  Boolean,  should  bits  under  be  saved  */ 

/*  colormap  to  be  associated  with  window  */ 

/*  Boolean,  is  colormap  currently  installed*/ 

/*  IsUnmapped,  IsUnviewable,  IsViewable  */ 

/*  events  all  people  have  interest  in*/ 

/*  my  event  mask  */ 

/*  set  of  events  that  should  not  propagate  */ 

/*  Boolean  value  for  override-redirect  */ 


F.3.31  XWindowChanges 

XWindowChanges  describes  a  configuration  for  a  window.  Used  in  XConf  igure- 
window,  which  can  change  the  screen  layout  and  therefore  can  be  intercepted  by  the  win 
dow  manager.  This  sets  some  of  the  remaining  members  of  xwindowAttributes  that 
cannot  be  set  with  XChangeWindowAttributes  or  XCreateWindow. 

typedef  struct  { 

int  x,  y; 

int  width,  height; 

int  border_width; 

Window  sibling; 

int  stack_mode; 
}  XWi  ndo wCh an ge • ; 


F.3.32  XWMHints 


xwMHints  describes  various  application  preferences  for  communication  to  the  window 
manager  via  the  XA_WM_HINTS  property.  Used  in  xsetWMHints  and  XGetWMHints. 


typedef  struct  { 
long  flags; 
Bool  input; 


/*  marks  defined  fields  in  structure  */ 

/*  does  application  need  window  manager  for 

*  keyboard  input  */ 

/*  see  below  */ 


/*  pixmap  to  be  used  as  icon 


int  initial_state; 
Pixmap  icon_pixmap; 
Window  icon_window; 
int  icon  x,  icon  y; 
Pixmap  icon_mask; 
XID  window_group;        /*  ID  of  related  window  group  */ 
/*  this  structure  may  be  extended  in  the  future  */ 
}  XWMHints; 


window  to  be  used  as  icon 
initial  position  of  icon  ' 
icon  mask  bitmap  */ 
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Symbol  Reference 


This  appendix  presents  an  alphabetical  listing  of  the  symbols  used  in  Xlib.  The  routines  in 
parentheses  following  the  descriptions  indicate  the  routines  associated  with  those  symbols. 

A 

Above  Specifies  that  the  indicated  window  is  placed  above  the  indi 

cated  Sibling  window.  (XConf  igureWindow) 

AllHints  XA_WM_HINTS  property,  stores  optional  information  for  the 

window    manager.    If  AllHints    is   set,   all    members  of 

XA_WM_HINTS  are  Set   (XGetWMHints,  XSetWMHints) 

AllocAll  Creates  a  colormap  and  allocates  all  of  its  entries.  Available 

for  the  DirectColor,  Grayscale,  and  Pseudocolor  visual 
Classes  only.  (XCreateColormap) 

AllocNone  Creates    a    colormap    and    allocates    none    of   its    entries. 

(XCreateColormap) 

AllowExposures  Specifies  that  exposures  are  generated  when  the  screen  is 

restored  after  blanking.    (XGetScreenSaver,  XSetScreen- 
Saver) 

AllTemporary  Specifies  that  the  resources  of  all  clients  that  have  terminated 

in  RetainTemporary  (see  XSetCloseDownMode)  should  be 
killed.  (XKillClient) 

AllValues  Mask  used  by  xparseGeometry;  returns  those  set  by  user. 

AlreadyGrabbed  Specifies  that  the  pointer  or  keyboard  is  actively  grabbed  by 

another  client.   (XGrabKeyboard,  XGrabPointer) 

Always  Advises  the  server  to  maintain  contents  even  when  the  window 

is     unmapped.      (XChangeWindowAttributes,    XCreate- 
Window) 

AnyButton  Specifies  that  any  button  is  to  be  grabbed  (XGrabButton)  or 

ungrabbed  (xungrabButton)  or  that  any  button  will  trigger  a 
ButtonPress  or  ButtonRelease  event 

AnyKey  Specifies  that  any  key  is  to  be  grabbed  or  ungrabbed.  (XGrab- 

Key,XUngrabKey) 

AnyModifier  Specifies  a  modifier  keymask  for  XGrabButton,  XGrabKey, 

and  XUngrabKey,  and  for  the  results  of  XQueryPointer. 
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AnyP roper ty Type 
ArcChord 

ArcPieSlice 
AsyncBoth 

AsyncKeyboard 

AsyncPointer 

AutoRepeatModeDefault 

AutoRepeatModeOff 

AutoRepeatModeOn 


B 

BadAccess 

BadAlloc 
BadAtom 
BadColor 
BadCursor 

BadDrawable 

BadFont 

BadGC 

BadlDChoice 

Badlmplementation 

BadLength 

BadMatch 


Specifies  that  the  property  from  a  specified  window  should  be 
returned  regardless  of  its  type.  (xcetwindowProperty) 

Value  of  the  arc_mode  member  of  the  GC:  specifies  that  the 
area  between  the  arc  and  a  line  segment  joining  the  endpoints 

Of  the  arc  is  filled.   (XSetArcMode) 

Value  of  the  arc_mode  member  of  the  GC:  specifies  that  the 
area  filled  is  delineated  by  the  arc  and  two  line  segments  con 
necting  the  ends  of  the  arc  to  the  center  point  of  the  rectangle 
defining  the  arc.  (XSetArcMode) 

Specifies  that  pointer  and  keyboard  event  processing  resume 
normally  if  both  the  pointer  and  the  keyboard  are  frozen  by  the 
client  when  XAliowEvents  is  called  with  AsyncBoth. 

(XAllowEvents) 

Specifies  that  keyboard  event  processing  resumes  normally  if 
the  keyboard  is  frozen  by  the  client  when  XAllowEvents  is 
called  with  AsyncPointer.  (XAllowEvents) 
Specifies  that  pointer  event  processing  resumes  normally  if  the 
pointer  is  frozen  by  the  client  when  XAllowEvents  is  called 
with  AsyncPointer.  (XAllowEvents) 

Value  of  auto_repeat_mode:  specifies  that  the  key  or  key 

board  is  set  to  the  default  setting  for  the  server,  (xchange- 

KeyboardControl.XGetKeyboardControl) 

Value  of  auto_repeat_mode:    specifies  that  no  keys  will 

repeat.        (XChangeKeyboardControl,       XGetKeyboard- 

Control) 

Value  of  auto_repeat_mode:  specifies  that  keys  that  are  set 

to  auto_repeat  will  do  SO.    (XChangeKeyboardControl 
XGetKeyboardControl) 

Used  by  non-fatal  error  handlers  only,  meaning  depends  on 

Used  by  non-fatal  error  handlers  only,  insufficient  resources. 
Used  by  non-fatal  error  handlers  only,  parameter  not  an  Atom. 
Used  by  non-fatal  error  handlers  only,  no  such  colormap. 

Used  by  non-fatal  error  handlers  only,  parameter  not  a  Cur- 
sor. 


Used  by  non-fatal  error  handlers  only,  parameter  not  a  Font 
Used  by  non-fatal  error  handlers  only,  parameter  not  a  GC 


n0t  in 


or 


Used  by  non-fatal  error  handlers  only,  server  is  defective 
d  by  non-fatal  error  handlers  only,  request  length  incorrect. 
1  by  non-fatal  error  handlers  only,  parameter  mismatch 
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BadName 
BadPixmap 

BadRequest 
BadValue 

BadWindow 

Below 

BitmapFile Invalid 

BitmapNoMemory 

BitmapOpenFailed 

BitmapSuccess 

Bottomlf 

Buttonl 

ButtonlMask 
ButtonlMotionMask 

Button2 

Button2Mask 
Button2MotionMask 

Buttons 

ButtonSMask 
Button3MotionMask 

Button4 
Button4Mask 


Used  by  non-fatal  error  handlers  only,  font  or  color  name  does 
not  exist. 

Used  by  non-fatal  error  handlers  only,  parameter  not  a  Fix- 
map. 
Used  by  non-fatal  error  handlers  only,  bad  request  code. 

Used  by  non-fatal  error  handlers  only,  integer  parameter  out  of 
range. 

Used  by  non-fatal  error  handlers  only,  parameter  not  a  win 
dow. 

Specifies  that  the  indicated  window  is  placed  below  the  indi 
cated  sibling  window.  (XConf  igureWindow) 

Specifies  that  a  file  does  not  contain  valid  bitmap  data. 

(XReadBitmapFile.XWriteBitmapFile) 

Specifies    that   insufficient    working    storage    is   allocated. 

(XReadBitmapFile,XWriteBitmapFile) 

Specifies  that  a  file  cannot  be  opened.  (XReadBitmapFile, 
XWriteBitmapFile) 

Specifies  that  a  file  is  readable  and  valid.  (XReadBitmap 
File,  XWriteBitmapFile) 

Specifies  that  the  indicated  window  is  placed  at  the  bottom  of 
the  stack  if  it  is  obscured  by  the  indicated  sibling  window. 
(XConfigureWindow) 

Specifies  that  buttonl  is  to  be  grabbed  (XGrabButton)  or 

ungrabbed  (XUngrabButton). 

Returns  the  current  state  of  buttonl.  (XQueryPointer) 

Specifies  that  any  buttonl  MotionNotify  events  are  to  be 
selected  for  this  window.  A  MotionNotify  event  reports 
pointer  movement,  (xselectlnput) 

Specifies  that  button2  is  to  be  grabbed  (XGrabButton)  or 

ungrabbed  (XUngrabButton). 

Returns  the  current  state  of  button2.  (XQueryPointer) 

Specifies  that  any  button2  MotionNotify  events  are  to  be 
selected  for  this  window.  A  MotionNotify  event  reports 
pointer  movement,  (xselectlnput) 

Specifies  that  button3  is  to  be  grabbed  (XGrabButton)  or 

ungrabbed  (XUngrabButton). 

Returns  the  current  state  of  buttons.  (XQueryPointer) 

Specifies  that  any  buttons  MotionNotify  events  are  to  be 
selected  for  this  window.  A  MotionNotify  event  reports 
pointer  movement,  (xselectlnput) 

Specifies  that  button4  is  to  be  grabbed  (XGrabButton)  or 

ungrabbed  (XUngrabButton). 

Returns  the  current  state  of  button4.  (XQueryPointer) 
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Button4MotionMask 


Buttons 


Button5Mask 
Button5MotionMask 


ButtonMotionMask 


ButtonPress 
ButtonPressMask 


ButtonRe lease 
ButtonReleaseMask 


c 

CapButt 

CapNotLast 

CapProjecting 

CapRound 
CenterGravity 

CirculateNotify 

CirculateRequest 

ClientlconState 


ClientMessage 
ClipByChildren 


Specifies  that  any  button4  MotionNotify  events  are  to  be 

selected  for  this  window.   A  MotionNotify  event  reports 

pointer  movement.  (XSelectlnput) 

Specifies  that  button5  is  to  be  grabbed  (XGrabButton)  or 

ungrabbed  (XUngrabButton). 

Returns  the  current  state  of  buttons.  (XQueryPointer) 

Specifies  that  any  buttons  MotionNotify  events  are  to  be 

selected  for  this  window.   A  MotionNotify  event  reports 

pointer  movement.  (XSelectlnput) 

Specifies  that  any  button  MotionNotify  events  are  to  be 
selected  for  this  window.  A  MotionNotify  event  reports 
pointer  movement.  (XSelectlnput) 

Event  type. 

Specifies  that  any  ButtonPress  events  are  to  be  selected  for 
this  window.  A  ButtonPress  event  reports  that  a  pointing 
device  button  has  been  pressed.  (XSelectlnput) 

Event  type. 

Specifies  that  any  ButtonRelease  events  are  to  be  selected 
for  this  window.  A  ButtonRelease  event  reports  that  a 
pointing  device  button  has  been  released.  (XSelectlnput) 

Value  of  the  cap_sty  le  member  of  a  GC:  specifies  that  lines 
will  be  square  at  the  endpoint  with  no  projection  beyond. 

(XSetLineAt tributes) 

Value  of  the  cap_styie  member  of  a  GC:  equivalent  to 
CapButt  except  that,  for  a  line_width  of  0  or  1,  the  final 
endpoint  is  not  drawn.  (XSetLineAttributes) 
Value  of  the  caP_styie  member  of  a  GC:  specifies  that  lines 
will  be  square  at  the  end  but  with  the  path  continuing  beyond 
the  endpoint  for  a  distance  equal  to  half  the  line_width. 

(XSetLineAttributes) 

Value  of  the  cap_sty  le  member  of  a  GC:  specifies  that  lines 
will  be  terminated  by  a  circular  arc.  (XSetLineAttributes) 
When  a  window  is  resized,  specifies  the  new  location  of  the 
contents  or  the  children  of  the  window.  (xchangeWindow- 
Attributes, XCreateWindow) 
Event  type. 
Event  type. 

Indicates  that  the  client  wants  its  icon_window  to  be  visible. 
If  an  icon_window  is  not  available,  it  wants  its  top-level  win 
dow  visible.  (Value  for  initial_state  member  of 

XWMHints.) 

Event  type. 

Value  of  the  subwindow_mode  member  of  the  GC:  specifies 
Ujat  graphics  requests  will  not  draw  through  viewable  children 
(XSetSubwindowMode) 
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ColormapChangeMask 

Colormap Ins tailed 

ColormapNotify 
ColormapUninstalled 

Complex 

Conf igureNotif y 
Conf igureRequest 
ControlMap Index 


ControlMask 

Convex 

CoordModeOrigin 

CoordModePrevious 

CopyFromParent 

CreateNotify 

CurrentTime 

CursorShape 

CWBackingPixel 
CWBackingP lanes 
CWBackingStore 
CWBackPixel 
CWBackPixmap 

CWBitGravity 
CWBorderPixel 


Specifies  that  ColormapNotify  events  are  to  be  selected  for 
the  window.  A  ColormapNotify  event  reports  colormap 
changes.  (XSelect Input) 

In  a  ColormapNotify  event,  specifies  that  the  colormap  is 
installed. 

Event  type. 

In  a  ColormapNotify  event,  specifies  that  the  colormap  is 
uninstalled. 

Specifies  that  paths  may  self-intersect  in  polygon  shapes. 
(XFillPolygon) 

Event  type. 
Event  type. 

Identifies  one  of  eight  modifiers  to  which  keycodes  can  be 
mapped.  (XDeleteModifiermapEntry,  XGetModif ier- 
Mapping,  XInsertModif iermapEntry,  XLookupKeysym, 
XSetModifierMapping) 

Specifies  a  modifier  keymask  for  XGrabButton,  XGrabKey, 
XUngrabButton,  and  XUngrabKey,  and  for  the  results  of 
XQueryPointer. 

Specifies  that  a  polygon's  path  is  wholly  convex.  (XF ill- 
Polygon) 

Specifies  that  all  coordinates  are  relative  to  the  origin  of  the 
drawable.  (XDrawLines,  XDrawPoints,  XFillPolygon) 

Specifies  that  all  coordinates  are  relative  to  the  previous  point 
(the  first  point  is  relative  to  the  origin).  (XDrawLines, 
XDrawPoints, XFillPolygon) 

Specifies  that  a  window's  border  pixmap,  visual  ID,  or  class 
should  be  copied  from  the  window's  parent  (xchange- 
WindowAttributes, XCreateWindow) 

Event  type. 

Specifies  time  in  most  time  arguments. 

Specifies  the  "best"  supported  cursor  size  available  on  the  dis 
play  hardware.  (XQueryBestSize) 

Mask  to  set  the  backing_pixel  window  attribute. 
(XChangeWindowAttributes, XCreateWindow) 

Mask  to  set  the  backing_pianes  window  attribute. 
(XChangeWindowAttributes,  XCreateWindow) 

Mask  to  set  the  backing_store  window  attribute. 
(XChangeWindowAttributes,  XCreateWindow) 

Mask  to  set  the  background_pixei  window  attribute. 
(XChangeWindowAttributes, XCreateWindow) 

Mask  to  set  the  background_pixmap  window  attribute. 
(XChangeWindowAttributes,  XCreateWindow) 

Mask  to  set  the  bit_gravity  window  attribute. 
Mask  to  set  the  border_pixel  window  attribute. 
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CWBorderPixmap 
CWBorderWidth 

CWColormap 

CWCursor 

CWDont Propagate 

CWEventMask 

CWHeight 

CWOverrideRedirect 

CWSaveUnder 

CWSibling 

CWStackMode 

CWWidth 

CWWinGravity 

CWX 

CWY 

DEF 

DefaultBlanking 
Default Exposures 

DestroyAll 

DestroyNotify 
DirectColor 

DisableAccess 
DisableScreenlnterval    Internal  to  Xlib. 


Mask  to  set  the  border_pixmap  window  attribute. 

Mask    to    set    a    new    width    for    the    window's    border. 

(XConfigureWindow) 

Mask  to  set  the  colormap  window  attribute,    (xchange- 
WindowAttributes,  XCreateWindow) 

Mask   to   set  the   cursor   window  attribute,    (xchange- 

WindowAttributes,  XCreateWindow) 

Mask  to  set  the  do_not_propagate_mask  window  attribute. 
(XChangeWindowAttributes,  XCreateWindow) 

Mask  to  set  the  event_mask  window  attribute.    (XChange- 
WindowAttributes,  XCreateWindow) 

Mask  to  set  a  new  height  for  the  window,   (xconf  igure- 
Window) 

Mask   to   set   the   override_redirect    window    attribute. 

(XChangeWindowAttributes,  XCreateWindow) 

Mask  to  set  the  save_under  window  attribute.    (XChange 
WindowAttributes,  XCreateWindow) 

Mask  to  specify  a  sibling  of  the  window,  used  in  stacking 
operations.  (XConfigureWindow) 

Mask  to  set  a  new  stack  mode  for  the  window.  (XConfigure 


Mask  to  set  a  new  width  for  the  window.   (XConfigure 


Mask  to  set  the  win_gravity  window  attribute.    (XChange 
WindowAttributes,  XCreateWindow) 
Mask  to  set  a  new  X  value  for  the  window's  position 

(XConfigureWindow) 

Mask  to  set  a  new  Y  value  for  the  window's  position 

(XConfigureWindow) 

Specifies    default    screen    saver   screen   blanking,     (xcet- 

ScreenSaver, XSetScreenSaver) 

Specifies  that  the  default  <??what  default??>  will  govern 
whether  or  not  exposures  are  generated  when  the  screen  is 
restored  after  blanking.  (XGetScreenSaver,  XSetScreen 
Saver) 

Specifies  that  all  resources  associated  with  a  client/server  con 
nection  will  be  freed  when  the  client  process  dies,  (xset- 

CloseDownMode) 

Event  type. 
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DisableScreenSaver 
DoBlue 


DoGreen 

DontAllowExposures 
DontCareState 

DontPreferBlanking 
DoRed 

EastGravity 
Enable Access 


EnterNotify 
EnterWindowMask 


EvenOddRule 


Expose 
ExposureMask 


FamilyChaos 
FamilyDECnet 
Family Internet 
FillOpaqueStippled 


Internal  to  Xlib. 

Sets  or  changes  the  read/write  colormap  cell  that  corresponds 
to  the  specified  pixel  value  to  the  hardware  color  that  most 
closely  matches  the  specified  blue  value.  (xstoreCoior, 
XStoreColors, XStoreNamedColor) 

Sets  or  changes  the  read/write  colormap  cell  that  corresponds 
to  the  specified  pixel  value  to  the  hardware  color  that  most 
closely  matches  the  specified  green  value.  (xstoreCoior, 
XStoreColors, XStoreNamedColor) 

Specifies  that  exposures  are  not  generated  when  the  screen  is 
restored  after  blanking.  (XGetScreenSaver,  XSetScreen- 
Saver) 

Indicates  that  the  client  does  not  know  or  care  what  the  initial 
state  of  the  client  is  when  the  top-level  window  is  mapped. 
Obsolete  in  R4.  (Value  for  initial_state  member  of 

XWMHints.) 

Specifies  no  screen  saver  screen  blanking,  (xcet Screen- 
Saver,  XSetScreenSaver) 

Sets  or  changes  the  read/write  colormap  cell  that  corresponds 
to  the  specified  pixel  value  to  the  hardware  color  that  most 
closely  matches  the  specified  red  value.  (xstoreCoior, 

XStoreColors, XStoreNamedColor) 

When  a  window  is  resized,  specifies  the  new  location  of  the 
contents  or  the  children  of  the  window.  (xchangeWindow- 
Attributes, XCreateWindow) 

Specifies  that  the  host  access  list  should  be  checked  before 
allowing  access  to  clients  running  on  remote  hosts  (access  con 
trol  is  enabled).  (XSetAccessControl) 

Event  type. 

Specifies  that  any  EnterNotify  events  are  to  be  selected  for 
this  window.  An  EnterNotify  event  reports  pointer  window 
entry.  (XSelectlnput) 

Value  of  the  f  ill_rule  member  of  a  GC:  specifies  that  areas 
overlapping  an  odd  number  of  times  should  not  be  part  of  the 

region.   (XPolygonRegion,  XSetFillRule) 

Event  type. 

Specifies  that  any  exposure  event  except  GraphicsExpose  or 
NoExpose  is  to  be  selected  for  the  window.  An  Expose  event 
reports  when  a  window  or  a  previously  invisible  part  of  a  win 
dow  becomes  visible,  (xseiect input) 

Specifies  an  address  in  the  ChaosNet  network.  (XAddHost) 
Specifies  an  address  in  the  DECnet  network.  (XAddHost) 
Specifies  an  address  in  the  Internet  network.  (XAddHost) 

Value  of  the  fill_style  member  of  a  GC:  specifies  that 
graphics  should  be  drawn  using  stipple,  using  the  fore 
ground  pixel  value  for  set  bits  in  stipple  and  the  background 
pixel  value  for  unset  bits  in  pixel.  (xsetFiiistyle) 
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FillSolid 

FillStippled 

FillTiled 

First Ext ensionError 
FocusChangeMask 

Focusln 
FocusOut 
FontChange 
FontLeftToRight 

FontRightToLeft 
ForgetGravity 

G 

GCArcMode 

GCBackground 

GCCapStyle 

GCClipMask 

GCClipXOrigin 

GCClipYOrigin 

GCDashList 


Value  of  the  f  iii_styie  member  of  a  GC:  specifies  that 
graphics  should  be  drawn  using  the  foreground  pixel  value. 
(XSetFillStyle) 

Value  of  the  fill_style  member  of  a  GC:  specifies  that 
graphics  should  be  drawn  using  the  foreground  pixel  value 
masked  by  stipple.  (XSetFillStyle) 

Value  of  the  f  ill_style  member  of  a  GC:  specifies  that 
graphics  should  be  drawn  using  the  tile  pixmap.  (xset- 
FillStyle) 

Use  if  writing  extension. 

Specifies  that  any  Focusln  and  FocusOut  events  are  to  be 

selected  for  this  window.   Focusln  and  FocusOut  events 

report  changes  in  keyboard  focus,  (xselect  input) 

Event  type. 

Event  type. 

Internal  to  Xlib. 

Reports  that,  using  the  specified  font,  the  string  would  be 

drawn  left  to  right.  (XQueryFont,  XQueryTextExtents, 
XQueryTextExtentslG,  XTextExtents,  XText- 

ExtentslG) 

Reports  that,  using  the  specified  font,  the  string  would  be 

drawn  right  to  left.  (XQueryFont,  XQueryTextExtents, 
XQueryTextExtentslG,  XTextExtents,  XText- 

Extentsl6) 

Specifies  that  window  contents  should  always  be  discarded 
after  a  size  change.  (XChangeWindowAttributes, 
XCreateWindow) 

Mask  to  set  the  arc_mode  component  Of  a  GC.  (XChangeGC 
XCopyGC.XCreateGC) 

Mask  to  set  the  background  component  of  a  GC.  (xchange- 

GC, XCopyGC,  XCreateGC) 

Mask  to  set  the  caP_styie  component  of  a  GC.  (xchanqe- 

GC, XCopyGC,  XCreateGC) 

Mask  to  set  the  clip_mask  component  of  a  GC.  (xchanqe- 

GC, XCopyGC,  XCreateGC) 

Mask  to  set  the  clip_x_origin  of  the  clip  mask. 
(.XChangeGC,  XCopyGC,  XCreateGC) 

Mask   to   set   the    ciip_y_0rigin    of   the    clip  mask. 

(.XChangeGC,  XCopyGC,  XCreateGC) 

Mask  to  set  the  dashes  component  of  a  GC.  (XChangeGC, 

XCopyGC.XCreateGC) 
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GCDashOffset 

GCFillRule 

GCFillStyle 

GCFont 

GCForeground 

GCFunction 

GCGraphicsExposures 

GCJoinStyle 

GCLastBit 
GCLineStyle 

GCLineWidth 

GCPlaneMask 

GCStipple 

GCSubwindowMode 

GCTile 

GCTileStipXOrigin 

GCTileStipYOrigin 

GrabFrozen 

GrablnvalidTime 

GrabModeAsync 

GrabModeSync 

GrabNotViewable 


Mask    to    set    the    dash_offset    component    of   a   GC. 

(XChangeGC, XCopyGC, XCreateGC) 

Mask  to  set  the  f  ill_rule  component  of  a  GC.  (xchange- 

GC,  XCopyGC,  XCreateGC) 

Mask  to  set  the  f  ill_style  component  of  a  GC.  (xchange- 
GC, XCopyGC, XCreateGC) 

Mask  to  set  the  font  component  of  a  GC.    (XChangeGC, 

XCopyGC, XCreateGC) 

Mask  to  set  the  foreground  component  of  a  GC.  (XChange- 
GC, XCopyGC, XCreateGC) 

Mask  to  set  the  function  component  of  a  GC.  (XChangeGC, 

XCopyGC, XCreateGC) 

Mask  to  set  the  graphics_exposures  component  of  a  GC. 

(XChangeGC,  XCopyGC,  XCreateGC) 

Mask  to  set  the  join_style  component  of  a  GC.  (xchange- 
GC, XCopyGC, XCreateGC) 

Higher  than  last  GC  mask  value. 

Mask  to  set  the  line_style  component  Of  a  GC.  (XChange- 
GC, XCopyGC, XCreateGC) 

Mask  to  set  the  line_width  component  of  a  GC.  (xchange- 
GC, XCopyGC,  XCreateGC) 

Mask  to  set  the  plane_mask  component  of  a  GC.  (XChange- 
GC, XCopyGC,  XCreateGC) 

Mask  to  set  the  stipple  component  of  a  GC.  (XChangeGC, 

XCopyGC, XCreateGC) 

Mask  to  set  the  subwindow_mode  component  of  a  GC. 
(XChangeGC, XCopyGC, XCreateGC) 

Mask  to  set  the  tile  component  of  a  GC.    (XChangeGC, 

XCopyGC, XCreateGC) 

Mask    to    set    the    ts_x_origin    component    of   a   GC. 

(XChangeGC, XCopyGC, XCreateGC) 

Mask    to    set    the    ts_y_origin    component    of   a    GC. 

(XChangeGC,  XCopyGC,  XCreateGC) 

Specifies  that  the  pointer  is  frozen  by  an  active  grab  of  another 
Client.  (XGrabKeyboard,  XGrabPointer) 

Specifies  that  the  indicated  grab  time  is  involved  (earlier  than 
the  last  keyboard  grab  time  or  later  than  the  current  server 
time).  (XGrabKeyboard,  XGrabPointer) 

Specifies  the  pointer  or  keyboard  mode.  (XGrabButton, 
XGrabKey, XGrabKeyboard,  XGrabPointer) 

Specifies  the  pointer  or  keyboard  mode.    (XGrabButton, 

XGrabKey, XGrabKeyboard, XGrabPointer) 

Specifies  that  the  grab_window  is  not  viewable.  (XGrab 
Keyboard,  XGrabPointer) 


Appendix  G:  Symbol  Reference 


673 


GrabSuccess 

GraphicsExpose 

GravityNotify 

Grayscale 

GXand 


GXandlnverted 
GXandReverse 

GXclear 

GXcopy 

GXcopy In verted 

GXequiv 

GXinvert 
GXnand 

GXnoop 
GXnor 

GXor 
GXorlnverted 

GXorReverse 

GXset 
GXxor 

HU 

HeightValue 

HostDelete 
Hostlnsert 
IconicState 

IconMaskHint 


Specifies  a  successful  pointer  or  keyboard  grab.    (XGrab- 

Keyboard, XGrabPointer) 
Event  type. 
Event  type. 

Visual    class,    read/write.     (XGetvisualinfo,    XMat< 
Visuallnfo) 

Value  of  the  function  member  of  the  GC:  used  with  source 
and  destination  pixels  to  generate  final  destination  pixel  val 
ues:  STC  AND  dst.  (XChangeGC,  XCreateGC,  XSet- 
Function) 

(NOT  src)  AND  dst.  (XChangeGC,  XCreateGC,  XSet- 
Function) 

src  AND  (NOT  dst).  (XChangeGC,  XCreateGC,  XSet- 
Function) 

Set  dst  10  0.  (XChangeGC,  XCreateGC,  XSetFunction) 
src.  (XChangeGC,  XCreateGC,  XSetFunction) 
(NOT  src).  (XChangeGC,  XCreateGC,  XSetFunction) 
(NOT    src)    XOR    dst.     (XChangeGC,    XCreateGC,    XSet 
Function) 

(NOT  dst).  (XChangeGC,  XCreateGC,  XSetFunction) 
(NOT  src)  OR  (NOT  dst).   (XChangeGC,  XCreateGC,  XSet 
Function) 

dst.  (XChangeGC,  XCreateGC,  XSetFunction) 
(NOT    src)    AND    (NOT   dst).     (XChangeGC,    XCreateGC, 
XSetFunction) 

src  OR  dst.  (XChangeGC,  XCreateGC,  XSetFunction) 
(NOT    src)     OR    dst.      (XChangeGC,    XCreateGC,    XSet 
Function) 

STC  OR  (NOT  dst).  (XChangeGC,  XCreateGC,  XSet 
Function) 

set  pixel.  (XChangeGC,  XCreateGC,  XSetFunction) 
src  XOR  dst.  (XChangeGC,  XCreateGC,  XSetFunction) 


Represents  a  user-specified  window  height  in  the  standard 
window  geometry  string.  (XParseGeometry) 
Used  internally  to  distinguish  XAddHost  and  XRemoveHost. 
Used  internally  to  distinguish  XAddHost  and  XRemoveHost. 

Indicates  that  the  client  wants  to  be  iconified  when  the  top- 
level  window  is  mapped.  (Value  for  initial_state  mem 
ber  Of  XWMHints.) 

In  the  XA  WM  HINTS  property,  the  icon  pixmap  mask  mask 
communicates  to  the  window  manager  a  bitmap  that  deter 
mines  which  pixels  in  icon_pixmap  are  drawn  on  the  icon 

vvMUk-W.  ( v::--3tWMHints,  XSetWMHints) 
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IconPixmapHint 

IconPositionHint 

IconWindowHint 

IgnoreState 
InactiveState 
Include Inferiors 

InputFocus 
InputHint 

InputOnly 
InputOutput 

IsCursorKey 

IsFunctionKey 

IsKeypadKey 

IsMiscFunctionKey 

IsModifierKey 

IsPFKey 

IsUnmapped 

I sUn viewable 

IsViewable 

JoinBevel 


In  the  XA_WM_HINTS  property,  the  icon  pixmap  mask  commu 
nicates  to  the  window  manager  the  pattern  used  to  distinguish 
this  icon  from  other  clients.  (xcetWMHints,  xsetWMHints) 

In  the  XA_WM_HINTS  property,  the  position  mask  communi 
cates  to  the  window  manager  the  preferred  initial  position  of 
the  icon.  (XGetWMHints,  XSetWMHints) 

In  the  XA_WM_HINTS  property,  the  icon  window  mask  commu 
nicates  to  the  window  manager  that  icon_window  contains  a 
window  that  should  be  used  instead  of  creating  a  new  one. 

(XGetWMHints, XSetWMHints) 

Indicates  that  the  client  wants  the  window  manager  to  ignore 
this  window.  (Value  for  initial_state  member  of 

XWMHints.) 

Indicates  that  the  client  wants  to  be  inactive  when  the  top-level 
window  is  mapped.  Obsolete  in  R4.  (Value  for  ini- 
tial_state  member  of  XWMHints.) 

Value  of  the  subwindow_mode  member  of  the  GC:  specifies 
that  graphics  requests  will  draw  through  viewable  children. 

(XSetSubwindowMode) 

Specifies  that  the  event  will  be  sent  to  the  focus  window, 
regardless  of  the  position  of  the  pointer.  (xsendEvent) 

In  the  XA_WM_HINTS  property,  the  input  member  mask  com 
municates  to  the  window  manager  the  keyboard  focus  model 
used  by  the  application.  (XGetWMHints,  XSetWMHints) 

InputOnly  is  a  window  class  in  which  windows  may  receive 
input  but  may  not  be  used  to  display  output  (xcreate- 
Window) 

InputOutput  is  a  window  class  in  which  windows  may 
receive  input  and  may  be  used  to  display  output  (xcreate- 

Window) 

Keysym  class  macro. 
Keysym  class  macro. 
Keysym  class  macro. 
Keysym  class  macro. 
Keysym  class  macro. 
Keysym  class  macro. 

Means  that  the  window  is  unmapped.  (XGetwindow- 
Attributes) 

Means  that  the  window  is  mapped  but  is  unviewable  because 
some  ancestor  is  unmapped.  (XGetwindowAttributes) 

Means  that  the  window  is  currently  viewable.  (XGetwindow 
Attributes) 

Value  of  the  join_style  member  of  a  GC:  specifies  Cap- 
Butt  enpoint  styles,  with  the  triangular  notch  filled,  (xset- 
LineAttributes) 
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JoinMiter 
JoinRound 

KL 

KBAutoRepeatMode 

KBBellDuration 

KBBellPercent 

KBBellPitch 

KBKey 

KBKeyClickPercent 

KBLed 

KBLedMode 

KeymapNotify 
KeymapStateMask 


KeyPress 
KeyPressMask 

KeyRelease 
KeyReleaseMask 

LASTEvent 

Last Ext ens ionError 

LeaveNotify 

LeaveWindowMask 


Value  of  the  join_styie  member  of  a  GC:  specifies  that  the 
outer  edges  of  the  two  lines  should  extend  to  meet  at  an  angle. 
(XSetLineAttributes) 

Value  of  the  join_style  member  of  a  GC:  specifies  that  the 
lines  should  be  joined  by  a  circular  arc  with  diameter  equal  to 

the  line_width,  centered  On  the  join  point.  (XSetLine 
Attributes) 


Mask     to     specify     keyboard     auto-repeat     preferences. 

(XChangeKeyboardControl,  XGetKeyboardControl) 

Mask     to     specify     keyboard     bell-duration     preferences. 

(XChangeKeyboardControl,  XGetKeyboardControl) 

Mask     to     specify     keyboard     base-volume     preferences. 
(XChangeKeyboardControl,  XGetKeyboardControl) 
Mask  to  specify  keyboard  bell-pitch  preferences.    (XChange 
KeyboardControl,  XGetKeyboardControl) 
Mask  to  specify  the  keycode  of  the  key  whose  auto-repeat  sta 
tus     will     be     changed     to     the     setting     specified     by 
auto_repeat_mode.    (XChangeKeyboardControl,  XGet 
KeyboardControl) 

Mask    to    set    keyboard    key    click-volume    preferences. 

(XChangeKeyboardControl,  XGetKeyboardControl) 
Mask    to    specify     keyboard     led    preferences.      (XChange 
KeyboardControl,  XGetKeyboardControl) 
Mask  to  specify  keyboard  led_mode  preferences.    (XChange 
KeyboardControl,  XGetKeyboardControl) 
Event  type. 

Specifies  that  any  KeymapNotify  events  are  to  be  selected  for 
this  window.  A  KeymapNotify  event  notifies  the  client  about 
the  state  of  the  keyboard  when  the  pointer  or  keyboard  focus 
enters  a  window,  (xselect  Input) 
Event  type. 

Specifies  that  any  KeyPress  events  are  to  be  selected  for  this 
window.  A  KeyPress  event  reports  that  a  keyboard  key  has 
been  pressed,  (xselectinput) 
Event  type. 

Specifies  that  any  KeyRelease  events  are  to  be  selected  for 
this  window.  A  KeyRelease  event  reports  that  a  keyboard 
key  has  been  released,  (xselectinput) 
Bigger  than  any  event  type  value.  For  extensions. 
Use  if  writing  extension. 
Event  type. 

Specifies  that  any  LeaveNotify  events  are  to  be  selected  for 
^window.  A  LeaveNotify  event  reports  when  the  pointer 
leaves  the  window,  (xselectinput) 
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LedModeOf  f  Value  of  ied_mode:  specifies  that  the  states  of  all  the  lights 

are  not  changed.  (XChangeKeyboardControl,  XGet- 
KeyboardControl) 

LedModeOn  Value  of  ied_mode:  specifies  that  the  states  of  all  the  lights 

are  changed.  (XChangeKeyboardControl,  XGet- 
KeyboardControl) 

LineDoubieDash  Value  of  the  line_style  member  of  a  GC:   specifies  that 

dashes  are  drawn  with  the  foreground  pixel  value  and  gaps 
with  the  background  pixel  value.  (xsetLineAttributes) 

LineOnOffDash  Value  of  the  line_style  member  of  a  GC:   specifies  that 

only  the  dashes  are  drawn  with  the  foreground  pixel  value,  and 
cap_style  applies  to  each  dash.  (XSetLineAttributes) 

LineSolid  Value  of  the  iine_style  member  of  a  GC:  specifies  that  the 

full  path  of  the  line  is  drawn  using  the  foreground  pixel  value. 
(XSetLineAttributes) 

LockMapindex  Identifies  one  of  eight  modifiers  to  which  keycodes  can  be 

mapped.  (XDeleteModifiermapEntry,  XGetModif ier- 
Mapping,  XInsertModif iermapEntry,  XLookupKeysym, 
XSetModifierMapping) 

LockMask  Specifies  a  modifier  keymask  for  XGrabButton,  XGrabKey, 

XUngrabButton,  and  XUngrabKey,  and  for  the  results  of 
XQueryPointer. 

LowerHighest  Specifies  that  the  stacking  order  of  children  should  be  circu 

lated  down.  (XCirculateSubwindows) 

LSBFirst  In  image  structure,  specifies  the  byte  order  used  by  VAXes. 

(XCreatelmage) 

M 

MapNot  i  f  y  Event  type. 

MappingBusy  Specifies  that,  in  pointer  or  modifier  mapping,  no  modifiers 

were  changed  because  new  keycodes  for  a  modifier  differ  from 
those  currently  defined  and  any  (current  or  new)  keys  for  that 
modifier  are  in  a  down  state.  (XSetModifierMapping, 

XSetPointerMapping) 

MappingFaiied  Specifies  that  pointer  or  modifier  mapping  failed.    (XSet 

ModifierMapping,  XSetPointerMapping) 

MappingKeyboard  In  a  MappingNotify  event,  reports  that  keyboard  mapping 

was  changed. 

MappingModif  ier  In  a  MappingNotify  event,  reports  that  keycodes  were  set  to 

be  used  as  modifiers. 
MappingNotify  Event  type. 

MappingPointer  In  a  MappingNotify  event,  reports  that  pointer  button  map 

ping  was  set 

MappingSuccess  Specifies  that  pointer  or  modifier  mapping  succeeded.   (XSet 

ModifierMapping,  XSetPointerMapping) 
MapReguest  Event  type. 
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MessageHint 
ModlMapIndex 

ModlMask 
Mod2MapIndex 

Mod2Mask 
Mod3MapIndex 

Mod3Mask 
Mod4MapIndex 

Mod4Mask 
ModSMapIndex 

ModSMask 


MotionNotify 
MSBFirst 

N 
NoEventMask 

NoExpose 
Nonconvex 


In  the  XA_WM_HINTS  property,  the  message  member  mask 
communicates  to  the  window  manager  the  <??what??>. 

(XGetWMHints, XSetWMHints) 

Identifies  one  of  eight  modifiers  to  which  keycodes  can  be 

mapped.  (XDeleteModifiermapEntry,  XGetModif ier- 
Mapping,  XInsertModif iermapEntry,  XLookupKeysym, 
XSetModifierMapping) 

Specifies  a  modifier  keymask  for  XGrabButton,  XGrabKey, 
xungrabButton,  and  xungrabKey,  and  for  the  results  of 

XQueryPointer. 

Identifies  one  of  eight  modifiers  to  which  keycodes  can  be 

mapped.  (XDeleteModifiermapEntry,  XGetModif ier- 
Mapping,  XInsertModif iermapEntry,  XLookupKeysym, 
XSetModifierMapping) 

Specifies  a  modifier  keymask  for  XGrabButton,  XGrabKey, 
XUngrabButton,  and  XUngrabKey,  and  for  the  results  of 
XQueryPointer. 

Identifies  one  of  eight  modifiers  to  which  keycodes  can  be 
mapped.  (XDeleteModifiermapEntry,  XGetModif ier- 
Mapping,  XInsertModif iermapEntry,  XLookupKeysym, 
XSetModifierMapping) 

Specifies  a  modifier  keymask  for  XGrabButton,  XGrabKey, 
XUngrabButton,  and  XUngrabKey,  and  for  the  results  of 
XQueryPointer. 

Identifies  one  of  eight  modifiers  to  which  keycodes  can  be 
mapped.  (XDeleteModifiermapEntry,  XGetModif ier- 
Mapping,  XInsertModif iermapEntry,  XLookupKeysym, 
XSetModifierMapping) 

Specifies  a  modifier  keymask  for  XGrabButton,  XGrabKey, 
XUngrabButton,  and  XUngrabKey,  and  for  the  results  of 

XQueryPointer. 

Identifies  one  of  eight  modifiers  to  which  keycodes  can  be 

mapped.  (XDeleteModifiermapEntry,  XGetModif ier- 
Mapping,  XInsertModif iermapEntry,  XLookupKeysym 
XSetModifierMapping) 

Specifies  a  modifier  keymask  for  XGrabButton,  XGrabKey, 
XUngrabButton,  and  XUngrabKey,  and  for  the  results  of 

XQueryPointer. 
Event  type. 

In  image  structure,  specifies  the  byte  order  used  by  68000-fam- 
ily  systems.  (XCreatelmage) 


Specifies  that  no  events  are  to  be  selected  for  this  window 

(XSelectlnput) 
Event  type. 

Specifies  that  a  polygon's  path  does  not  self-intersect  but  that 
the  polygon  is  not  wholly  convex.  (XFiiiPolygon) 
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None 
NormalState 

NorthEastGravity 

NorthGravity 

NorthWestGravity 

NoSymbol 
NotifyAncestor 

NotifyDetailNone 

NotifyGrab 
NotifyHint 
Notifylnferior 

NotifyNone 

Not ifyNon linear 


Not if yNon linear- 
Virtual 


Specifies  a  universal  null  resource  or  null  atom. 

Indicates  that  the  client  wants  its  top-level  window  visible. 
(Value  for  initial_state  member  of  XWMHints.) 

When  a  window  is  resized,  specifies  the  new  location  of  the 
contents  or  the  children  of  the  window,  (xchangewindow- 

Attributes, XCreateWindow) 

When  a  window  is  resized,  specifies  the  new  location  of  the 
contents  or  the  children  of  the  window.  (xchangeWindow- 

Attributes, XCreateWindow) 

When  a  window  is  resized,  specifies  the  new  location  of  the 
contents  or  the  children  of  the  window,  (xchangewindow- 

Attributes, XCreateWindow) 

Specifies  the  keysym  for  no  symbol. 

In  EnterNotify,  Focusln,  FocusOut,  and  LeaveNotify 
events,  specifies  the  hierarchical  relationship  of  the  origin  and 
destination  windows. 

In  EnterNotify,  Focusln,  FocusOut,  and  LeaveNotify 

events,  specifies  the  hierarchical  relationship  of  the  origin  and 
destination  windows. 

In  EnterNotify,  Focusln,  FocusOut,  and  LeaveNotify 

events,  specifies  that  the  keyboard  or  pointer  was  grabbed. 
In    a   MotionNotify    event,    a    hint    that    specifies    that 

PointerMotionHintMask  was  selected. 

In  EnterNotify,  Focusln,  FocusOut,  and  LeaveNotify 
events,  specifies  the  hierarchical  relationship  of  the  origin  and 
destination  windows. 

In  EnterNotify,  Focusln,  FocusOut,  and  LeaveNotify 
events,  specifies  the  hierarchical  relationship  of  the  origin  and 
destination  windows. 

In  EnterNotify,  Focusln,  FocusOut, and  LeaveNotify 
events,  specifies  the  hierarchical  relationship  of  the  origin  and 
destination  windows. 

In  EnterNotify,  Focusln,  FocusOut,  and  LeaveNotify 

events,  specifies  the  hierarchical  relationship  of  the  origin  and 
destination  windows. 


NotifyNormal 

NotifyPointer 

NotifyPointerRoot 

NotifyUngrab 


In  a  MotionNotify  event,  a  hint  that  specifies  that  the  event 
is  real  but  may  not  be  up  to  date  since  there  may  be  many  more 
later  motion  events  on  the  queue.  In  EnterNotify,  Focus- 
in,  FocusOut,  and  LeaveNotify  events,  specifies  that  the 
keyboard  was  not  grabbed  at  the  time  the  event  was  generated. 

In  Focusln  and  FocusOut  events,  specifies  the  hierarchical 
relationship  of  the  origin  and  destination  windows. 

In  Focusln  and  FocusOut  events,  specifies  the  hierarchical 
relationship  of  the  origin  and  destination  windows. 

In  EnterNotify,  Focusln,  FocusOut,  and  LeaveNotify 
events,  specifies  that  the  keyboard  or  pointer  was  ungrabbed. 
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NotifyVirtual 


NotifyWhileGrabbed 
NotUseful 


NoValue 

OP 

Opposite 


OwnerGrabButtonMask 

PAllHints 

ParentRelative 

PAspect 

PBaseSize 

PlaceOnBottom 

PlaceOnTop 

PMaxSize 

PMinSize 

Point erMotionHintMask 

PointerMotionMask 

PointerRoot 

PointerWindow 

PPosition 


In  EnterNotify,  Focusln,  FocusOut,  and  LeaveNotify 
events,  specifies  the  hierarchical  relationship  of  the  origin  and 
destination  windows. 
EnterNotify,  Focusln,  FocusOut,  LeaveNotify  mode. 

Specifies  that  maintaining  the  contents  of  an  unmapped  win 
dow  is  unnecessary.  (xchangeWindowAttributes, 
XCreateWindow) 

Mask  used  by  XP  arse  Geometry;  returns  those  set  by  user. 

Specifies  that,  if  the  indicated  sibling  occludes  the  indicated 
window,  the  window  is  placed  at  the  top  of  the  stack;  if  the 
window  occludes  the  sibling,  the  window  is  placed  at  the  bot 
tom  of  the  stack.  (XConfigureWindow) 

Controls  the  distribution  of  button  events  to  a  client  between 
ButtonPress  and  ButtonRelease  events.  (XSelect- 
Input) 

Specifies  that  the  program  determined  the  window  hints. 

(XGetNormalHints,  XSetNormalHints) 

Specifies  that  a  window's  background  will  be  repainted  when 

it  is  moved.  (XSetWindowBackgroundPixmap) 

Specifies  that  the  program  determined  the  min  and  max  aspect 

ratio.  (XGetNormalHints,  XSetNormalHints) 

Specifies  that  the  program  determined  the  base  window  size. 

(XGetNormalHints,  XSetNormalHints) 

In  a  circulateNotify  event,  specifies  that  the  window  will 
be  placed  on  the  bottom  of  the  stack. 

In  a  circulateNotify  event,  specifies  that  the  window  will 
be  placed  on  the  top  of  the  stack. 

Specifies  that  the  program  determined  the  maximum  desired 

Window  Size.  (XGetNormalHints,  XSetNormalHints) 

Specifies  that  the  program  determined  the  minimum  desired 
Window  size.  (XGetNormalHints,  XSetNormalHints) 
Specifies  that  the  server  should  send  only  one  MotionNotif  y 
event  when  the  pointer  moves.  Used  in  concert  with  other 
pointer  motion  masks  to  reduce  the  number  of  events  gen 
erated.  (XSelect Input) 

Specifies  that  any  pointer  MotionNotify  events  are  to  be 
selected  for  this  window.  A  MotionNotify  event  reports 
pointer  movement,  (xselectinput) 

Specifies  the  ID  of  the  window  that  is  the  current  keyboard 
tOCUS.  (XGetlnputFocus,  XSetlnputFocus) 

Specifies  that  the  event  will  be  sent  to  the  window  that  the 
pointer  is  in.  (XSendEvent) 

Specifies  that  the  program  determined  the  window  position 

itNormalHints, XSetNormalHints) 
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PreferBlanking 

PResizelnc 

PropertyChangeMask 

PropertyDelete 
PropertyNewValue 

PropertyNotify 
P  ropMode Append 

PropModePrepend 

PropModeReplace 

Pseudocolor 

PSize 

PWinGravity 

R 

RaiseLowest 
Rectangleln 
RectangleOut 
RectanglePart 

ReleaseByFreeing 
Colormap 

ReparentNotify 
ReplayKeyboard 

ReplayPointer 


Specifies  screen  saver  screen  blanking.  (XGetScreenSaver, 

XSetScreenSaver) 

Specifies  that  the  program  determined  the  window  resize 
increments.  (XGetNormalHints,  XSetNormalHints) 

Specifies  that  any  PropertyNotify  events  are  to  be  selected 
for  this  window.  A  PropertyNotify  event  indicates  that  a 
property  of  a  certain  window  was  changed  or  deleted. 
(XSelectlnput) 

In  a  PropertyNotify  event,  specifies  that  a  property  of  a 
window  was  deleted. 

In  a  PropertyNotify  event,  specifies  that  a  property  of  a 
window  was  changed. 

Event  type. 

Appends    the    data    onto    the    end    of   the    existing    data. 

(XChangeProperty) 

Inserts  the  data  before  the  beginning  of  the  existing  data. 

(XChangeProperty) 

Discards  the  previous  property  and  stores  the  new  data. 

(XChangeProperty) 

Visual    class,    read/write.     (XGetvisualinfo,    XMatch- 

Visuallnfo) 

Specifies   that  the  program  determined   the  window  size. 

(XGetNormalHints,  XSetNormalHints) 

Specifies  that  the  program  determined  the  window  gravity. 

(XGetNormalHints,  XSetNormalHints) 


Specifies  that  the  stacking  order  of  children  should  be  circu 
lated  up.  (XCirculateSubwindows) 

Specifies  that  the  rectangle  is  inside  the  region.  (XRect- 
InRegion) 

Specifies  that  the  rectangle  is  completely  outside  the  region. 

(XRectlnRegion) 

Specifies   that   the   rectangle   is  partly   inside   the   region. 

(XRectlnRegion) 

Value  for  the  killid  field  of  XStandardColormap. 
(XSetRGBColormap  and  XGetRGBColormap) 

Event  type. 

Specifies  the  conditions  under  which  queued  events  are 
released:  ReplayKeyboard  has  an  effect  only  if  the  key 
board  is  grabbed  by  the  client  and  thereby  frozen  as  the  result 
of  an  event.  (XAllowEvents) 

Specifies  the  conditions  under  which  queued  events  are 
released:  ReplayPointer  has  an  effect  only  if  the  pointer  is 
grabbed  by  the  client  and  thereby  frozen  as  the  result  of  an 
event  (XAII OWE vents) 
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ResizeRedirectMask 


ResizeRequest 
RetainPermanent 


RetainTemporary 

RevertToNone 

RevertToParent 

RevertToPointerRoot 

s 

ScreenSaver Active 
ScreenSaverReset 

SelectionClear 
SelectionNotify 
SelectionRequest 
SetModeDelete 

SetModelnsert 
ShiftMapIndex 

ShiftMask 
SouthEast Gravity 


Specifies  that  any  ResizeRequest  events  should  be  selected 
for  this  window  when  some  other  client  (usually  the  window 
manager)  attempts  to  resize  the  window  on  which  this  mask  is 
selected.   (XSelect Input) 
Event  type. 

Specifies  that  resources  associated  with  a  client/server  connec 
tion  live  on  until  a  call  to  XKillClient.  If  AllTemporary 
is  specified  in  XKillClient,  the  resources  of  all  clients  that 
have  terminated  in  RetainTemporary  are  destroyed. 
<??vo!2  unclear  --  XKillClient  doc??>  (XSetClose- 
DownMode) 

Specifies  that  resources  associated  with  a  client/server  connec 
tion  live  on  until  a  call  to  XKillClient.  If  AllTemporary 
is  specified  in  XKillClient,  the  resources  of  all  clients  that 
have  terminated  in  RetainTemporary  are  destroyed,  (xset- 

CloseDownMode) 

Specifies  that  there  is  no  backup  keyboard  focus  window. 

(XGetlnputFocus, XSetlnputFocus) 

Specifies  that  the  backup  keyboard  focus  window  is  the  parent 

window.  (XGetlnputFocus,  XSetlnputFocus) 

Specifies  that  the  backup  keyboard  focus  window  is  the 

pointer  root  window.  (XGetlnputFocus,  XSetlnputFocus) 

Specifies  that  the  screen  saver  is  to  be  activated.   (xForce- 

ScreenSaver) 

Specifies  that  the  screen  saver  is  to  be  turned  off.  (XForce- 
ScreenSaver) 

Event  type. 
Event  type. 
Event  type. 
Specifies  that  a  subwindow  is  to  be  deleted  from  the  client's 

save-set.  (XChangeSaveSet) 

Specifies  that  a  subwindow  is  to  be  added  to  the  client's  save- 
set.  (XChangeSaveSet) 

Identifies  one  of  eight  modifiers  to  which  keycodes  can  be 

mapped.  (XDeleteModifiermapEntry,  XGetModif ier- 
Mapping,  XInsertModif iermapEntry,  XLookupKeysym 
XSetModifierMapping) 

Specifies  a  modifier  keymask  for  XGrabButton,  XGrabKey 
xungrabButton,  and  xungrabKey,  and  for  the  results  of 
XQueryPointer. 

When  a  window  is  resized,  specifies  the  new  location  of  the 
contents  or  the  children  of  the  window,  (xchangewindow- 
Attributes, XCreateWindow) 
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SouthGravity 
SouthWest Gravity 
StateHint 

StaticColor 
StaticGravity 

StaticGray 

StippleShape 

StructureNotifyMask 


SubstructureNotify- 
Mask 


SubstructureRedirect- 
Mask 


When  a  window  is  resized,  specifies  the  new  location  of  the 
contents  or  the  children  of  the  window,  (xchangewindow- 

Attributes, XCreateWindow) 

When  a  window  is  resized,  specifies  the  new  location  of  the 
contents  or  the  children  of  the  window.  (xchangeWindow- 
Attributes, XCreateWindow) 

In  the  XA_WM_HINTS  property,  the  window  state  mask  commu 
nicates  to  the  window  manager  whether  the  client  prefers  to  be 
in  iconified,  zoomed,  normal,  or  inactive  state.  (XGet- 

WMHints, XSetWMHints) 

Visual  class,  read-only.  (XGetVisuallnfo,  XMatch- 
Visuallnfo) 

Specifies  that  window  contents  should  not  move  relative  to  the 
origin  of  the  root  window.  (XChangeWindowAttribute, 
XCreateWindow) 

Visual  class,  read-only.  (XGetVisuallnfo,  XMatch- 
Visuallnfo) 

Specifies  the  "best"  supported  stipple  size  available  on  the  dis 
play  hardware.  (XQueryBestSize) 

Selects    a    group    of    event    types    (circuiateNotify, 

ConfigureNotify,  DestroyNotify,  GravityNotify, 
MapNotify,  ReparentNotify,  UnmapNotify)  that  report 
when  the  state  of  a  window  has  changed,  (xselect  input) 

Selects  a  group  of  event  types  (circuiateNotify, 
ConfigureNotify,  DestroyNotify,  GravityNotify, 
MapNotify,  ReparentNotify,  UnmapNotify)  that  report 

when  the  state  of  a  window  has  changed,  plus  an  event  that 
indicates  that  a  window  has  been  created.  It  monitors  all  the 
subwindows  of  the  window  specified  in  the  xselect  Input 
call  that  used  this  mask. 

The  three  event  types  selected  by  this  mask  (circuiate- 

Request,  Conf igureRequest,  and  MapRequest)  can  be 
used  by  the  window  manager  to  intercept  and  cancel  window- 
configuration-changing  requests  made  by  other  clients. 
(XSelectlnput) 


Success 
SyncBoth 


SyncKeyboard 


SyncPointer 


Indicates  that  everything  is  okay. 

Specifies  that  pointer  and  keyboard  event  processing  resumes 

normally,    until    the    next   ButtonPress,    ButtonRelease, 

Keypress,  or  KeyRelease  event,  if  the  pointer  and  the  key 
board  are  both  frozen  by  the  client  when  XAllowEvents  is 

called  with  SyncBoth.  (XAllowEvents) 

Specifies  that  key  event  processing  resumes  normally,  until  the 
next  ButtonPress  or  ButtonRelease  event,  if  the  key 
board  is  frozen  by  the  client  when  XAllowEvents  is  called 
with  SyncPointer.  (XAllowEvents) 

Specifies  that  pointer  event  processing  resumes  normally,  until 
the  next  ButtonPress  or  ButtonRelease  event,  if  the 
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TU 

TileShape 
Top  If 

TrueColor 
UnmapGravity 

UnmapNotify 
Unsorted 

USPosition 
USSize 

vw 

VisibilityChangeMask 


VisibilityFully- 
Obscured 


VisibilityNotify 

VisibilityPartially- 
Obscured 

VisibilityUnobscured 

VisualAllMask 

VisualBitsPerRGBMask 

VisualBlueMaskMask 

VisualClassMask 


pointer  is  frozen  by  the  client  when  XAllowE vents  is  called 

with  SyncPointer.  (XAllowEvents) 


Specifies  the  "best"  supported  tile  size  available  on  the  display 
hardware.  (XQueryBestSize) 

Specifies  that  the  indicated  window  is  placed  on  top  of  the 
stack  if  it  is  obscured  by  the  indicated  sibling  window. 

(XConfigureWindow) 

Visual  class,  read-only.  (XGetVisuallnfo,  XMatch- 
Visuallnfo) 

Specifies  that  the  child  is  unmapped  when  the  parent  is  resized 
and  an  UnmapNotify  event  is  generated.  (xchangeWindow- 
Attributes, XCreateWindow) 

Event  type. 

Specifies  that  the  ordering  of  rectangles  specified  for  a  particu 
lar  GC  is  arbitrary.  (XSetClipRectangles) 

Specifies  that  the  user  provided  a  position  value  for  the  win 
dow.  (XGetNormalHints, XSetNormalHints) 

Specifies  that  the  user  provided  a  size  value  for  the  window. 

(XGetNormalHints, XSetNormalHints) 


Specifies  that  any  VisibilityNotify  events  are  to  be 
selected  for  this  window,  except  when  the  window  becomes 
not  viewable.  A  VisibilityNotify  event  reports  any 
changes  in  the  window's  visibility,  (xselect  input) 

In  a  VisibilityNotify  event,  specifies  that  the  window  is 
fully  obscured. 


Event  type. 

In  a  VisibilityNotify  event,  specifies  that  the  window  is 
partially  obscured. 

In  a  VisibilityNotify  event,  specifies  that  the  window  is 
unobscured. 

Determines  which  elements  in  a  template  are  to  be  matched 

(XGetVisuallnfo, XMatchVisuallnfo) 

Determines  which  elements  in  a  template  are  to  be  matched 

(XGetVisuallnfo, XMatchVisuallnfo) 

Determines  which  elements  in  a  template  are  to  be  matched. 

(XGetVisuallnfo, XMatchVisuallnfo) 

Determines  which  elements  in  a  template  are  to  be  matched 

(XGetVisuallnfo, XMatchVisuallnfo) 
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VisualColormapSize- 

Mask 
VisualDepthMask 

VisualGreenMaskMask 

VisuallDMask 

VisualNoMask 

VisualRedMaskMask 

VisualScreenMask 

WestGravity 

WhenMapped 

WidthValue 
WindingRule 

WindowGroupHint 
WithdrawnState 

X 

XA_ARC 

XA_ATOM 

XA_BITMAP 

XA_CAP_HEIGHT 
XA_CARDINAL 

XA_COLORMAP 

XA_COPYRIGHT 
XA  CURSOR 


Determines  which  elements  in  a  template  are  to  be  matched. 

(XGetVisuallnfo, XMatchVisuallnfo) 

Determines  which  elements  in  a  template  are  to  be  matched. 
(XGetVisuallnfo, XMatchVisuallnfo) 

Determines  which  elements  in  a  template  are  to  be  matched. 

(XGetVisuallnfo, XMatchVisuallnfo) 

Determines  which  elements  in  a  template  are  to  be  matched. 
(XGetVisuallnfo,  XMatchVisuallnfo) 

Determines  which  elements  in  a  template  are  to  be  matched. 

(XGetVisuallnfo,  XMatchVisuallnfo) 

Determines  which  elements  in  a  template  are  to  be  matched. 

(XGetVisuallnfo, XMatchVisuallnfo) 

Determines  which  elements  in  a  template  are  to  be  matched. 

(XGetVisuallnfo, XMatchVisuallnfo) 

When  a  window  is  resized,  specifies  the  new  location  of  the 
contents  or  the  children  of  the  window,  (xchangewindow- 
Attributes, XCreateWindow) 

Advises  the  server  to  maintain  contents  of  obscured  regions 
when  the  window  is  unmapped,  (xchangewindow- 
Attributes, XCreateWindow) 

Represents  a  user-specified  window  width  in  the  standard  win 
dow  geometry  string.  (XParseGeometry) 

Value  of  the  f  ill_rule  member  of  a  GC:  specifies  that  areas 
overlapping  an  odd  number  of  times  should  be  part  of  the 

region.   (XPolygonRegion,  XSetFillRule) 

In  the  XA_WM_HINTS  property,  the  group  property  mask  com 
municates  to  the  window  manager  that  the  client  has  multiple 

top-level  windows.   (XGetWMHints.XSetWMHints) 

Indicates  that  the  client  wants  neither  its  top-level  nor  its  icon 
visible.  (Value  for  initial  state  member  of  xwMHints.) 


Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertseiection) 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertseiection) 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertseiection) 

Predefined  type  atom. 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertseiection) 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertseiection) 

Predefined  font  atom. 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertseiection) 
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XA_CUT_BUFFERO 
XA_CUT_BUFFER1 
XA_CUT_BUFFER2 
XA_CUT_BUFFER3 
XA_CUT_BUFFER4 
XA_CUT_BUFFER5 
XA_CUT_BUFFER6 
XA_CUT_BUFFER7 
XA_DRAWABLE 

XA_END_SPACE 

XA_FAMILY_NAME 

XA_FONT 

XA_FONT_NAME 
XA_FULL_NAME 
XA_INTEGER 

XA_ITALIC_ANGLE 

XA_LAST_PREDEFINED 

XA_MAX_SPACE 

XA_MIN_SPACE 

XA_NORM_SPACE 

XA_NOTICE 

XA_PIXMAP 

XA_POINT 

XA_POINT_SIZE 

XA_PRIMARY 

XA_QUAD_WIDTH 
XA_RECTANGLE 
XA_RESOLUTION 
XA_RESOURCE  MANAGER 


Represents  a  predefined  cut  buffer  atom. 
Represents  a  predefined  cut  buffer  atom. 
Represents  a  predefined  cut  buffer  atom. 
Represents  a  predefined  cut  buffer  atom. 
Represents  a  predefined  cut  buffer  atom. 
Represents  a  predefined  cut  buffer  atom. 
Represents  a  predefined  cut  buffer  atom. 
Represents  a  predefined  cut  buffer  atom. 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertselection) 

Specifies  the  additional  spacing  at  the  end  of  sentences. 
Predefined  font  atom. 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertselection) 
Predefined  font  atom. 
Predefined  font  atom. 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertselection) 

Specifies  the  angle  of  the  dominant  staffs  of  characters  in  the 
font 

Predefined  font  atom. 
Specifies  the  maximum  interword  spacing. 
Specifies  the  minimum  interword  spacing. 
Specifies  the  normal  interword  spacing. 
Predefined  font  atom. 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertselection) 
Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertselection) 
Specifies  the  point  size  of  this  font  at  the  ideal  resolution 
expressed  in  tenths  of  a  point. 

Specifies  the  primary  built-in  selection  atom  used  in  transfer 
ring  data  between  clients. 

"1  em"  as  in  TeX  but  expressed  in  units  of  pixels.  The  width 
of  an  m  in  the  current  font  and  point  size. 
Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertselection) 

i  per  point  at  which  this  font  was 


Specifies  a  predefined  resource  manager  property  containing 
default  values  for  user  preferences. 
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Specifies  a  predefined  colormap  atom  that  defines  the  "best" 
RGB  colormap  available  on  the  display. 

Specifies  a  predefined  colormap  atom  that  defines  an  all-blue 

colormap. 

Specifies  the  atom  of  the  type  property  that  specifies  the 

desired  format  for  the  data,  (xconvertseiection) 

Specifies  a  predefined  colormap  atom  that  defines  part  of  the 
system  default  colormap. 

Specifies  a  predefined  colormap  atom  that  defines  the  "best" 
gray-scale  colormap  available  on  the  display. 

Specifies  a  predefined  colormap  atom  that  defines  an  all-green 

colormap. 

Specifies  a  predefined  colormap  atom  that  defines  an  all-red 

colormap. 

Specifies   the   secondary   built-in    selection    atom   used   in 
transferring  data  between  clients. 

Specifies  the  vertical  extents  (in  pixels)  for  boxing  or  voiding 

characters. 

Specifies  the  vertical  extents  (in  pixels)  for  boxing  or  voiding 

characters. 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertseiection) 

XA_SUBSCRIPT_X  Specifies  the  X  offset  (in  pixels)  from  the  character  origin 

where  subscripts  should  begin. 

XA_SUBSCRIPT_Y  Specifies  the  Y  offset  (in  pixels)  from  the  character  origin 

where  subscripts  should  begin. 

XA_SUPERSCRIPT_X  Specifies  the  X  offset  (in  pixels)  from  the  character  origin 

where  superscripts  should  begin. 

XA_SUPERSCRIPT_Y  Specifies  the  Y  offset  (in  pixels)  from  the  character  origin 

where  superscripts  should  begin. 

XA_UNDERLINE_POSITION  Specifies  the  Y  offset  (in  pixels)  from  the  baseline  to  the  top  of 
the  underline. 

XA_UNDERLINE_THICKNESS Specifies  the  thickness  (in  pixels)  from  the  baseline  to  the  top 
of  the  underline. 


XA  RGB  BEST  MAP 


XA  RGB  BLUE  MAP 


XA  RGB  COLOR  MAP 


XA  RGB  DEFAULT  MAP 


XA  RGB  GRAY  MAP 


XA  RGB  GREEN  MAP 


XA  RGB  RED  MAP 


XA  SECONDARY 


XA  STRIKEOUT  ASCENT 


XA  STRIKEOUT  DESCENT 


XA  STRING 


XA  VISUALID 


XA  WEIGHT 


XA  WINDOW 


XA  WM  CLASS 


Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertseiection) 

Specifies  the  weight  or  boldness  of  the  font,  expressed  as  a 
value  between  0  and  1000. 

Specifies  the  atom  of  the  type  property  that  specifies  the 
desired  format  for  the  data,  (xconvertseiection) 

The  XA_WM_CLASS  property  is  a  string  containing  two  null- 
separated  elements,  res_class  and  res_name,  that  are 
meant  to  be  used  by  clients  both  as  a  means  of  permanent  iden 
tification  and  as  the  handles  by  which  both  the  client  and  the 
window  manager  obtain  resources  related  to  the  window. 
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XA_WM_CLIENT_MACHINE 

XA_WM_COMMAND 
XA_WM_HINTS 

XA_WM_ICON_NAME 

XA_WM_ICON_SIZE 
XA_WM_NAME 

XA_WM_NORMAL_H INTS 

XA_WM_SIZE_HINTS 
XA_WM_TRANS IENT_FOR 

XA_WM_ZOOM_HINTS 

XA_X_HEIGHT 

XCNOENT 

XCNOMEM 

XCSUCCESS 

XK_* 

XNegative 

XValue 
XYBitmap 


XYPixmap 
X_PROTOCOL 
X_PROTOCOL  REVISION 


The  XA_WM_CLIENT_MACHINE  property  is  a  string  forming 
the  name  of  the  machine  running  the  client,  as  seen  from  the 
machine  running  the  server. 

The  XA_WM_COMMAND  property  stores  the  shell  command  and 
arguments  used  to  invoke  the  application. 

The  XA_WM_HINTS  property  contains  hints  stored  by  the  win 
dow  manager  that  provide  a  means  of  communicating  optional 
information  from  the  client  to  the  window  manager. 

The  XA_WM_ICON_NAME  property  is  an  uninterpreted  string 
that  the  client  wishes  displayed  in  association  with  the  window 
when  it  is  iconified  (for  example,  in  an  icon  label). 

The  window  manager  may  set  the  XA_WM_ICON_SIZE  prop 
erty  on  the  root  window  to  specify  the  icon  sizes  it  allows. 

The  XA_WM_NAME  property  is  an  uninterpreted  string  that  the 
client  wishes  displayed  in  association  with  the  window  (for 
example,  a  window  headline  bar). 

The    XA_WM_NORMAL_HINTS    property    is    an    XSizeHints 

structure  describing  the  desired  position  and  range  of  sizes  that 
are  preferable  for  each  top-level  window  in  normal  state. 
The  XA_WM_SIZE_HINTS  property  contains  hints  stored.. 

The  XA_WM_TRANSIENT_FOR  property  is  the  ID  of  another 
top-level  window. 

The  XA_WM_ZOOM_HINTS  property  is  an  XSizeHints  struc 
ture  describing  the  desired  position  and  range  of  sizes  that  are 
preferable  for  each  top-level  window  in  a  zoomed  state. 

"1  ex"  as  in  TeX  but  expressed  in  units  of  pixels,  often  the 
height  of  lower  case  x. 

Association  table  lookup  return  codes,  No  entry  in  table. 

Association  table  lookup  return  codes,  Out  of  memory. 

Association  table  lookup  return  codes,  No  error. 

Keysyms,  see  Appendix  H,  Keysym  Reference. 

Represents  a  user-specified  negative  X  offset  in  the  standard 

window  geometry  string.  (XParseGeometry) 

Represents  a  user-specified  positive  X  offset  in  the  standard 

window  geometry  string.  (XParseGeometry) 

XYBitmap  specified  the  format  for  an  image.  The  data  for  an 
mage  is  said  to  be  in  XYBitmap  format  if  the  bitmap  is  repre- 
ented  in  scan  line  order,  with  each  scan  line  made  up  of  multi 
ples  of  the  bitmaP_unit  and  padded  with  meaningless  bits 

(XGetlmage, XPutlmage) 

Depth  =  drawable  depth.  (XGetlmage,  XPut Image) 

Current  protocol  version. 

Current  minor  revision. 
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YZ 

YNegative 
YSorted 
YValue 
YXBanded 

YXSorted 

ZoomState 
ZPixmap 


Represents  a  user-specified  negative  Y  offset  in  the  standard 
window  geometry  String.  (XParseGeometry) 

Specifies  that  rectangles  specified  for  a  particular  GC  are  non- 
decreasing  in  their  Y  origin.  (XSetClipRectangles) 

Represents  a  user-specified  positive  Y  offset  in  the  standard 
window  geometry  String.  (XParseGeometry) 

Specifies  that,  in  addition  to  the  constraints  of  YXS  or  ted,  for 
every  possible  horizontal  Y  scan  line,  all  rectangles  that 
include  that  scan  line  have  identical  Y  origins  and  X  extents. 
(XSetClipRectangles) 

Specifies  that  rectangles  specified  for  a  particular  GC  are  non- 
decreasing  in  their  Y  origin  and  that  all  rectangles  with  an 
equal  Y  origin  are  nondecreasing  in  their  X  origin.  (XSet 
ClipRectangles) 

Indicates  that  the  client  wants  to  be  in  zoomed  state  when  the 
top-level  window  is  mapped.  Obsolete  in  R4.  (Value  for  in i- 

tial_state  member  of  XWMHints.) 

Depth  =  drawable  depth.  (XGet  Image,  XPut  Image) 
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H 

Keysyms 


This  appendix  provides  a  list  of  keysyms  and  a  brief  description  of  each  keysym.  Keysyms, 
as  you  may  remember,  are  the  portable  representation  of  the  symbols  on  the  caps  of  keys. 

The  normal  way  to  process  a  keyboard  event  is  to  use  XLookupKeysym  to  determine  the 
keysym  or,  if  the  application  allows  remapping  of  keys  to  strings,  it  may  use  XLookup- 
String  to  get  the  ASCH  string  mapped  to  the  key  or  keys  pressed.  This  allows  the  applica 
tion  to  treat  keys  in  a  simple  and  portable  manner,  and  places  the  responsibility  of  tailoring 
the  mapping  between  keys  and  keysyms  on  the  server  vendor.* 

Many  keysyms  do  not  have  obvious  counterparts  on  the  keyboard,  but  may  be  generated  with 
certain  key  combinations.  You  will  need  a  table  for  each  particular  model  of  hardware  you 
intend  the  program  to  work  on,  to  tell  you  what  key  combination  results  in  each  keysym  that 
is  not  present  on  the  caps  of  the  keyboard.  For  real  portability,  you  will  want  to  use  only  the 
keysyms  that  are  supported  on  all  vendors  equipment  you  intend  the  program  to  be  displayed 
on. 

The  keysyms  are  defined  in  two  standard  include  files:  <Xlllkeysym.h>  and  <Xlllkeysym- 
def.h>.  There  are  several  families  of  keysyms  defined  in  <Xlllkeysymdef.h>;  LATTN1, 
LATIN2,  LATIN3,  LATIN4,  KATAKANA,  ARABIC,  CYRILLIC,  GREEK,  TECHNICAL, 
SPECIAL,  PUBLISHING,  APL,  HEBREW,  and  MISCELLANY.  The  <Xlllkeysym.h>  file 
specifies  which  families  are  enabled.  Only  the  LATESfl,  LATIN2,  LATINS,  LATIN4, 
GREEK,  and  MISCELLANY  families  are  enabled  in  the  standard  <Xlllkeysym.h>  file,  proba 
bly  because  some  compilers  have  an  upper  limit  on  the  number  of  defined  symbols  that  are 
allowed. 

The  developers  of  X  at  MIT  say  that  to  the  best  of  their  knowledge  the  Latin,  Kana,  Arabic, 
Cyrillic,  Greek,  Technical,  APL,  and  Hebrew  keysym  sets  are  from  the  appropriate  ISO 
(International  Standards  Organization)  and/or  ECMA  international  standards.  There  are  no 
Technical,  Special  nor  Publishing  international  standards,  so  these  sets  are  based  on  Digital 
Equipment  Corporation  standards. 


*  While  keycode  information  is  not  necessary  for  normal  application  programming,  it  may  be  necessary  for  writing 
certain  programs  that  change  the  keycode  to  keysym  mapping.  If  you  are  writing  such  an  application,  you  will  need 
to  obtain  a  list  of  keycodes  and  their  normal  mappings  from  the  system  manufacturer.  Any  program  lhat  uses  this 
mapping  is  not  fully  portable. 
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Keysyms  are  four  byte  long  values.  In  the  standard  keysyms,  the  least  significant  8  bits  indi 
cate  a  particular  character  within  a  set  and  the  next  8  bits  indicate  a  particular  keysym  set 
The  order  of  the  sets  is  important  since  not  all  the  sets  are  complete.  Each  character  set  con 
tains  gaps  where  codes  have  been  removed  that  were  duplicates  with  codes  in  previous  (that 
is,  with  lesser  keysym  set)  character  sets. 

The  94  and  96  character  code  sets  have  been  moved  to  occupy  the  right  hand  quadrant  (deci 
mal  129  -  256),  so  the  ASCH  subset  has  a  unique  encoding  across  the  least  significant  byte 
which  corresponds  to  the  ASCII  character  code.  However,  this  cannot  be  guaranteed  in  the 
keysym  sets  of  future  releases  and  does  not  apply  to  all  of  the  MISCELLANY  set 

As  far  as  possible,  keysym  codes  are  the  same  as  the  character  code.  In  the  LATIN1  to 
LATIN4  sets,  all  duplicate  glyphs  occupy  the  same  position.  However,  duplicates  between 
GREEK  and  TECHNICAL  do  not  occupy  the  same  code  position.  Thus,  applications  wishing 
to  use  the  TECHNICAL  character  set  must  transform  the  keysym  using  an  array. 

The  MISCELLANY  set  is  a  miscellaneous  collection  of  commonly  occurring  keys  on  key 
boards.  Within  this  set,  the  keypad  symbols  are  generally  duplicates  of  symbols  found  on 
keys  on  the  alphanumeric  part  of  the  keyboard  but  are  distinguished  here  because  they  often 
have  distinguishable  keycodes  associated  with  them. 

There  is  a  difference  between  European  and  US  usage  of  the  names  Pilcrow,  Paragraph,  and 
Section,  as  shown  in  Table  H-l. 

Table  H-1.  European  vs.  US  usage  of  Pilcrow,  Paragraph,  and  Section  symbol  names 


US  name 

European  name 

Keysym  in  LATIN1 

Symbol 

Section  sign 
Paragraph  sign 

Paragraph  sign 
Pilcrow  sign 

XK_section 
XK_paragraph 

§ 

1 

X  has  adopted  the  names  used  by  both  the  ISO  and  ECMA  standards.  Thus,  XK_j>ara- 
graph  is  what  Europeans  call  the  pilcrow  sign,  and  XK_section  is  what  they  would  call 
the  paragraph  sign.  This  favors  the  US  usage. 


H.1   Keysyms  and  Description 

Tables  H-2  through  H-7  list  the  six  commonly  available  sets  of  keysyms  (MISCELLANY, 
LATIN1  through  LATIN4,  and  GREEK)  and  describe  each  keysym  briefly.  When  necessary 
and  possible,  these  tables  show  a  representative  character  or  characters  that  might  appear  on 
the  cap  of  the  key  or  on  the  screen  when  the  key  or  keys  corresponding  to  the  keysym  were 
typed. 
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Table  H-2.  MISCELLANY 


Keysym 


Description 


XK_BackSpace 

XK_Tab 

XK_Linefeed 

XK_Clear 

XK_Return 

XK_Pause 

XK_Escape 

XK_Delete 

XK_Multi_key 

XK_Kanji 

XK_Home 

XK_Left 

XK_Up 

XK_Right 

XK_Down 

XK_Prior 

XK_Next 

XK_End 

XK_Begin 

XK_Select 

XK_Print 

XK_Execute 

XK_Insert 

XK_Undo 

XK_Redo 

XK_Menu 

XK_Find 

XK_Cancel 

XK_Help 

XK_Break 

XK_Mode_s witch 

XK_script_switch 

XK_Num_Lock 

XK_KP_Space 

XK_KP_Tab 

XK_KP_Enter 

XK_KP_F1 

XK_KP_F2 

XK_KP_F3 

XK_KP_F4 

XK_KP_Equal 

XK_KP_Multiply 

XK  KP  Add 


Backspace,  Back  Space,  Back  Char 

Tab 

Linefeed,  LF 

Clear 

Return,  Enter 

Pause,  Hold,  Scroll  Lock 

Escape 

Delete,  Rubout 

Multi-key  character  preface 

Kanji,  Kanji  convert 

Home 

Left,  move  left,  left  arrow 

Up,  move  up,  up  arrow 

Right,  move  right,  right  arrow 

Down,  move  down,  down  arrow 

Prior,  previous 

Next 

End,EOL 

Begin,  BOL 

Select,  mark 

Print 

Execute,  run,  do 

Insert,  insert  here 

Undo,  oops 

Redo,  again 

Menu 

Find,  search 

Cancel,  stop,  abort,  exit 

Help,  question  mark 

Break 

Mode  switch,  script  switch, 

character  set  switch 

Alias  for  mode  switch,  script  switch, 

character  set  switch 

NumLock 

Keypad  Space 

Keypad  Tab 

Keypad  Enter 

Keypad  F1.PF1,  a 

Keypad  F2,PF2,b 

Keypad  F3,PF3,c 

Keypad  F4,  PF4,  d 

Keypad  equals  sign 

Keypad  multiplication  sign,  asterisk 

Keypad  plus  sign 
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Table  H-2.  MISCELLANY  (continued) 


Keysym 


Description 


XK_KP_Separator 

XK_KP_Subtract 

XK_KP_Decimal 

XK_KP_Divide 

XK_KP_0 

XK_KP_1 

XK_KP_2 

XK_KP_3 

XK_KP_4 

XK_KP_5 

XK_KP_6 

XK_KP_7 

XK_KP_8 

XK_KP_9 

XK_F1 

XK_F2 

XK_F3 

XK_F4 

XK_F5 

XK_F6 

XK_F7 

XK_F8 

XK_F9 

XK_F10 

XK_F11 

XK_L1 

XK_F12 

XK_L2 

XK_F13 

XK_L3 

XK_F14 

XK_L4 

XK_F15 

XK_L5 

XK_F16 

XK_L6 

XK_F17 

XK_L7 

XK_F18 

XK_L8 

XK_F19 

XK_L9 

XK_F20 

XK_L10 

XK  F21 


Keypad  separator,  comma 

Keypad  minus  sign,  hyphen 

Keypad  decimal  point,  full  stop 

Keypad  division  sign,  solidus 

Keypad  digit  zero 

Keypad  digit  one 

Keypad  digit  two 

Keypad  digit  three 

Keypad  digit  four 

Keypad  digit  five 

Keypad  digit  six 

Keypad  digit  seven 

Keypad  digit  eight 

Keypad  digit  nine 

Fl  function  key 

F2  function  key 

F3  function  key 

F4  function  key 

F5  function  key 

F6  function  key 

F7  function  key 

F8  function  key 

F9  function  key 

F10  function  key 

Fll  function  key 

LI  function  key 

F12  function  key 

L2  function  key 

F13  function  key 

L3  function  key 

F14  function  key 

L4  function  key 

F15  function  key 

L5  function  key 

F16  function  key 

L6  function  key 

F17  function  key 

L7  function  key 

F18  function  key 

L8  function  key 

F19  function  key 

L9  function  key 

F20  function  key 

L10  function  key 

F21  function  key 
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Table  H-2.  MISCELLANY  (continued) 


Keysym 

Description 

XK_R1 

Rl  function  key 

XK_F22 

F22  function  key 

XK_R2 

R2  function  key 

XK_F23 

F23  function  key 

XK_R3 

R3  function  key 

XK_F24 

F24  function  key 

XK   R4 

R4  function  key 

XK_F25 

F25  function  key 

XK   R5 

R5  function  key 

XK_F26 

F26  function  key 

XK_R6 

R6  function  key 

XK_F27 

F27  function  key 

XK_R7 

R7  function  key 

XK_F28 

F28  function  key 

XK_R8 

R8  function  key 

XK   F29 

F29  function  key 

XK_R9 

R9  function  key 

XK   F30 

F30  function  key 

XK_R10 

RIO  function  key 

XK_F31 

F31  function  key 

XK_R11 

Rll  function  key 

XK_F32 

F32  function  key 

XK_R12 

R12  function  key 

XK_R13 

F33  function  key 

XK_F33 

R13  function  key 

XK_F34 

F34  function  key 

XK_R14 

R14  function  key 

XK_F35 

F35  function  key 

XK_R15 

R15  function  key 

XK_Shift_L 

Left  Shift 

XK_Shift_R 

Right  Shift 

XK_Control_L 

Left  Control 

XK   Control    R 

Right  Control 

XK_Caps_Lock 

Caps  Lock 

XK_Shift_Lock 

Shift  Lock 

XK_Meta_L 

Left  Meta 

XK  Meta_R 

Right  Meta 

XK_Alt_L 

Left  Alt 

XK_Alt_R 

Right  Alt 

XK_Super_L 

Left  Super 

XK    Super   R 

Right  Super 

XK_Hyper_L 

Left  Hyper 

XK   Hyper    R 

Right  Hyper 
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Table  H-3.  LATIN1 


Keysym 

Description 

Character 

XK_space 

Space 

XK_exclam 

Exclamation  point 

! 

XK_quotedbl 

Quotation  mark 

" 

XK_numbersign 

Number  sign 

# 

XK_dollar 

Dollar  sign 

$ 

XK_percent 

Percent  sign 

% 

XK_ampersand 

Ampersand 

& 

XK_quoteright 

Apostrophe 

' 

XK_parenleft 

Left  parenthesis 

( 

XK  parenright 

Right  parenthesis 

) 

XK_asterisk 

Asterisk 

* 

XK_plus 

Plus  sign 

+ 

XK    comma 

Comma 

, 

XK_minus 

Hyphen,  minus  sign 

- 

XK_period 

Full  stop 

XK_slash 

Solidus 

/ 

XK    0 

Digit  zero 

0 

XK    1 

Digit  one 

1 

XK    2 

Digit  two 

2 

XK    3 

Digit  three 

3 

XK_4 

Digit  four 

4 

XK_5 

Digit  five 

5 

XK_6 

Digit  six 

6 

XK    7 

Digit  seven 

7 

XK_8 

Digit  eight 

8 

XK_9 

Digit  nine 

9 

XK_colon 

Colon 

: 

XK_semicolon 

Semicolon 

; 

XK_less 

Less  than  sign 

< 

XK_equal 

Equals  sign 

= 

XK_greater 

Greater  than  sign 

> 

XK_question 

Question  mark 

9 

XK   at 

Commercial  at 

@ 

XK_A 

Latin  capital  A 

A 

XK_B 

Latin  capital  B 

B 

XK_C 

Latin  capital  C 

C 
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Table  H-3.  LATIN1  (continued) 


Keysym 

Description 

Character 

XK_D 

Latin  capital  D 

D 

XK_E 

Latin  capital  E 

E 

XK_F 

Latin  capital  F 

F 

XK_G 

Latin  capital  G 

G 

XK_H 

Latin  capital  H 

H 

XK_I 

Latin  capital  I 

I 

XK_J 

Latin  capital  J 

J 

XK_K 

Latin  capital  K 

K 

XK_L 

Latin  capital  L 

L 

XK_M 

Latin  capital  M 

M 

XK   N 

Latin  capital  N 

N 

XK_0 

Latin  capital  O 

0 

XK_P 

Latin  capital  P 

P 

XK_Q 

Latin  capital  Q 

Q 

XK_R 

Latin  capital  R 

R 

XK    S 

Latin  capital  S 

S 

XK_T 

Latin  capital  T 

T 

XK_U 

Latin  capital  U 

U 

XK_V 

Latin  capital  V 

V 

XK   W 

Latin  capital  W 

W 

XK_X 

Latin  capital  X 

X 

XK_Y 

Latin  capital  Y 

Y 

XK_Z 

Latin  capital  Z 

Z 

XK_bracketleft 

Left  square  bracket 

[ 

XK_backslash 

Reverse  solidus 

\ 

XK_bracketright 

Right  square  bracket 

] 

XK   asciicircum 

Circumflex  accent 

* 

XK   underscore 

Low  line 

XK    quoteleft 

Grave  accent 

» 

XK_a 

Latin  small  a 

a 

XK_b 

Latin  small  b 

b 

XK_c 

Latin  small  c 

c 

XK_d 

Latin  small  d 

d 

XK_e 

Latin  small  e 

e 

XK_f 

Latin  small  f 

f 

XK    g 

Latin  small  g 

g 

XK   h 

Latin  small  h 

h 

XK_i 

Latin  small  i 

i 
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Table  H-3.  LATIN1  (continued) 


Keysym 

Description 

Character 

XK_j 

Latin  small  j 

j 

XK_k 

Latin  small  k 

k 

XK_1 

Latin  small  1 

1 

XK_m 

Latin  small  m 

m 

XK_n 

Latin  small  n 

n 

XK_o 

Latin  small  o 

0 

XK_p 

Latin  small  p 

P 

XK_q 

Latin  small  q 

q 

XK_r 

Latin  small  r 

r 

XK_s 

Latin  small  s 

s 

XK_t 

Latin  small  t 

t 

XK_u 

Latin  small  u 

u 

XK_v 

Latin  small  v 

V 

XK_w 

Latin  small  w 

w 

XK_x 

Latin  small  x 

X 

XK_y 

Latin  small  y 

y 

XK_z 

Latin  small  z 

z 

XK_braceleft 

Left  brace 

{ 

XK_bar 

Vertical  line 

1 

XK   braceright 

Right  brace 

} 

XK_asciitilde 

Tilde 

^ 

XK_nobreakspace 

No-break  space 

XK   exclamdown 

Inverted  exclamation  mark 

i 

XK_cent 

Cent  sign 

0 

XK_sterling 

Pound  sign 

£ 

XK_currency 

Currency  sign 

D 

XK_yen 

Yen  sign 

¥ 

XK_brokenbar 

Broken  vertical  bar 

, 

XK_section 

Paragraph  sign,  section  sign 

§ 

XK_diaeresis 

Diaeresis 

XK_copyright 

Copyright  sign 

© 

XK_ordfeminine 

Feminine  ordinal  indicator 

i 

XK_guillemotleft 

Left  angle  quotation  mark 

« 

XK_notsign 

Not  sign 

—  i 

XK_hyphen 

Short  horizontal  hyphen 

XK_registered 

Registered  trade  mark  sign 

® 

XK_macron 

Macron 

XK_degree 

Degree  sign,  ring  above 

0 
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Table  H-3.  LATIN1  (continued) 


Keysym 


Description 


Character 


XK_plusminus 

XK_twosuperior 

XK_threesuperior 

XK_acute 

XK_mu 

XK_paragraph 

XK_periodcentered 

XK_cedilla 

XK_onesuperior 

XK_masculine 

XK_gu  illemotright 

XK_onequarter 

XK_onehalf 

XK_threequarters 

XK_questiondown 

XK_Agrave 

XK_Aacute 

XK_Acircumflex 

XK_Atilde 

XK_Adiaeresis 

XK_Aring 

XK_AE 

XK_Ccedilla 

XK_E grave 

XK_Eacute 

XK_Ecircumflex 

XK_Ediaeresis 

XK_Igrave 

XK_Iacute 

XK_Icircumflex 

XK_Idiaeresis 

XK_Eth 

XK_Ntilde 

XK_Ograve 

XK_Oacute 

XK_Ocircumflex 

XK_Otilde 

XK  Odiaeresis 


Plus-minus  sign 

Superscript  two 

Superscript  three 

Acute  accent 

Micro  sign 

Pilcrow  sign 

Middle  dot 

Cedilla 

Superscript  one 

Masculine  ordinal  indicator 

Right  angle  quotation  mark 

Vulgar  fraction  one  quarter 

Vulgar  fraction  one  half 

Vulgar  fraction  three  quarters 

Inverted  question  mark 

Latin  capital  A  with  grave  accent 

Latin  capital  A  with  acute  accent 

Latin  capital  A  with  circumflex  accent 

Latin  capital  A  with  tilde 

Latin  capital  A  with  diaeresis 

Latin  capital  A  with  ring  above 

Latin  capital  diphthong  AE 

Latin  capital  C  with  cedilla 

Latin  capital  E  with  grave  accent 

Latin  capital  E  with  acute  accent 

Latin  capital  E  with  circumflex  accent 

Latin  capital  E  with  diaeresis 

Latin  capital  I  with  grave  accent 

Latin  capital  I  with  acute  accent 

Latin  capital  I  with  circumflex  accent 

Latin  capital  I  with  diaeresis 

Icelandic  capital  ETH 

Latin  capital  N  with  tilde 

Latin  capital  O  with  grave  accent 

Latin  capital  O  with  acute  accent 

Latin  capital  O  with  circumflex  accent 

Latin  capital  O  with  tilde 

Latin  capital  O  with  diaeresis 


A 
A 

A 
A 
A 

A 
JE 

C 

E 
E 
E 
E 
I 
I 
I 
I 

N 

6 
6 
6 
6 
6 
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Table  H-3.  LATIN1  (continued) 


Keysym 

Description 

Character 

XK_multiply 

Multiplication  sign 

X 

XK_Ooblique 

Latin  capital  O  with  oblique  stroke 

0 

XK_Ugrave 

Latin  capital  U  with  grave  accent 

U 

XK_Uacute 

Latin  capital  U  with  acute  accent 

U 

XK_Ucircumflex 

Latin  capital  U  with  circumflex  accent 

U 

XK_Udiaeresis 

Latin  capital  U  with  diaeresis 

u 

XK_Yacute 

Latin  capital  Y  with  acute  accent 

Y 

XK_Thorn 

Icelandic  capital  THORN 

XK_s  sharp 

German  small  sharp  s 

XK_agrave 

Latin  small  a  with  grave  accent 

a 

XK_aacute 

Latin  small  a  with  acute  accent 

& 

XK_acircumflex 

Latin  small  a  with  circumflex  accent 

a 

XK_atilde 

Latin  small  a  with  tilde 

a 

XK_adiaeresis 

Latin  small  a  with  diaeresis 

a 

XK   aring 

Latin  small  a  with  ring  above 

a 

XK   ae 

Latin  small  diphthong  ae 

33 

XK_ccedilla 

Latin  small  c  with  cedilla 

£ 

XK_egrave 

Latin  small  e  with  grave  accent 

e 

XK_eacute 

Latin  small  e  with  acute  accent 

£ 

XK_ecircumflex 

Latin  small  e  with  circumflex  accent 

e 

XK_ediaeresis 

Latin  small  e  with  diaeresis 

e- 

XK_igrave 

Latin  small  i  with  grave  accent 

i 

XK_iacute 

Latin  small  i  with  acute  accent 

i 

XK_icircumflex 

Latin  small  i  with  circumflex  accent 

i 

XK_idiaeresis 

Latin  small  i  with  diaeresis 

i 

XK_eth 

Icelandic  small  eth 

XK_ntilde 

Latin  small  n  with  tilde 

fi 

XK_ograve 

Latin  small  o  with  grave  accent 

6 

XK_oacute 

Latin  small  o  with  acute  accent 

6 

XK_ocircumflex 

Latin  small  o  with  circumflex  accent 

6 

XK_otilde 

Latin  small  o  with  tilde 

Q 

XK_odiaeresis 

Latin  small  o  with  diaeresis 

6 

XK_division 

Division  sign 

+ 

XK_oslash 

Latin  small  o  with  oblique  stroke 

0 

XK   ugrave 

Latin  small  u  with  grave  accent 

U 

XK_uacute 

Latin  small  u  with  acute  accent 

u 

XK_ucircumflex 

Latin  small  u  with  circumflex  accent 

u 

XK_udiaeresis 

-atin  small  u  with  diaeresis 

u 
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Table  H-3.  LATIN1  (continued) 


Keysym 

Description 

Character 

XK_yacute 
XK   thorn 
XK   ydiaeresis 

Latin  small  y  with  acute  accent 
Icelandic  small  thorn 
Latin  small  y  with  diaeresis 

y 
y 
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Table  H-4.  LATIN2 


Keysym 

Description 

Character 

XK_Aogonek 

Latin  capital  Awithogonek 

A 

XK  breve 

Breve 

" 

XK   Lstroke 

Latin  capital  L  with  stroke 

L 

XK   Lcaron 

Latin  capital  L  with  caron 

L 

XK   Sacute 

Latin  capital  S  with  acute  accent 

S 

XK_Scaron 

Latin  capital  S  with  caron 

S 

XK_Scedilla 

Latin  capital  S  with  cedilla 

§ 

XK_Tcaron 

Latin  capital  T  with  caron 

f 

XK_Zacute 

Latin  capital  Z  with  acute  accent 

Z 

XK   Zcaron 

Latin  capital  Z  with  caron 

z 

XK_Zabovedot 

Latin  capital  Z  with  dot  above 

z 

XK_aogonek 

Latin  small  a  with  ogonek 

9 

XK_ogonek 

Ogonek 

. 

XK_lstroke 

Latin  small  1  with  stroke 

1 

XK    Icaron 

Latin  small  1  with  caron 

1 

XK    sacute 

Latin  small  s  with  acute  accent 

& 

XK   caron 

Caron 

* 

XK_scaron 

Latin  small  s  with  caron 

§ 

XK_scedilla 

Latin  small  s  with  cedilla 

§ 

XK_tcaron 

Latin  small  t  with  caron 

I 

XK_z  acute 

Latin  small  z  with  acute  accent 

z 

XK_doubleacute 

Double  acute  accent 

- 

XK_zcaron 

Latin  small  z  with  caron 

I 

XK_zabovedot 

Latin  small  z  with  dot  above 

z 

XK_Racute 

Latin  capital  R  with  acute  accent 

f 

XK   Abreve 

Latin  capital  A  with  breve 

A 

XK_Cacute 

Latin  capital  C  with  acute  accent 

C 

XK_Ccaron 

Latin  capital  C  with  caron 

C 

XK_Eogonek 

Latin  capital  E  with  ogonek 

E 

XK_Ecaron 

Latin  capital  E  with  caron 

E 

XK_Dcaron 

Latin  capital  D  with  caron 

D 

XK_Nacute 

Latin  capital  N  with  acute  accent 

N 

XK_Ncaron 

Latin  capital  N  with  caron 

N 

XK_Odoubleacute 

Latin  capital  O  with  double  acute  accent 

6 

XK_Rcaron 

Latin  capital  R  with  caron 

R 

XK_Uring 

Latin  capital  U  with  ring  above 

U 

XK_Udoubleacute 

Latin  capital  U  with  double  acute  accent 

U 

XK_Tcedilla 

Latin  capital  T  with  cedilla 

T 
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Table  H-4.  LATIN2  (continued) 


Keysym 

Description 

Character 

XK_racute 

Latin  small  r  with  acute  accent 

f 

XK_abreve 

Latin  small  a  with  breve 

a 

XK_cacute 

Latin  small  c  with  acute  accent 

c 

XK_ccaron 

Latin  small  c  with  caron 

c 

XK   eogonek 

Latin  small  e  with  ogonek 

c 

XK   ecaron 

Latin  small  e  with  caron 

5 

XK   dcaron 

Latin  small  d  with  caron 

a 

XK   nacute 

Latin  small  n  with  acute  accent 

ri 

XK_ncaron 

Latin  small  n  with  caron 

ft 

XK    odoubleacute 

Latin  small  o  with  double  acute  accent 

6 

XK   rcaron 

Latin  small  r  with  caron 

f 

XK   uring 

Latin  small  u  with  ring  above 

u 

XK   udoubleacute 

Latin  small  u  with  double  acute  accent 

u 

XK_t  cedilla 

Latin  small  t  with  cedilla 

t 

XK_abovedot 

Dot  above 

Appendix  H:  Keysyms 


703 


Table  H-5.  LATINS 


Keysym 

Description 

Character 

XK_Hstroke 

Latin  capital  H  with  stroke 

XK   Hcircumflex 

Latin  capital  H  with  circumflex  accent 

H 

XK_Iabovedot 

Latin  capital  I  with  dot  above 

i 

XK_Gbreve 

Latin  capital  G  with  breve 

6 

XK   Jcircumflex 

Latin  capital  J  with  circumflex  accent 

J 

XK_hstroke 

Latin  small  h  with  stroke 

XK_hcircumflex 

Latin  small  h  with  circumflex  accent 

h 

XK_idotless 

Small  dotless  i 

i 

XK_gbreve 

Latin  small  g  with  breve 

g 

XK_jcircumflex 

Latin  small  j  with  circumflex  accent 

J 

XK_Cabovedot 

Latin  capital  C  with  dot  above 

C 

XK_Ccircumflex 

Latin  capital  C  with  circumflex  accent 

C 

XK_Gabovedot 

Latin  capital  G  with  dot  above 

G 

XK_Gcircumflex 

Latin  capital  G  with  circumflex  accent 

G 

XK_Ubreve 

Latin  capital  U  with  breve 

U 

XK_Scircumflex 

Latin  capital  S  with  circumflex  accent 

S 

XK_cabovedot 

Latin  small  c  with  dot  above 

c 

XK   ccircumflex 

Latin  small  c  with  circumflex  accent 

c 

XK   gabovedot 

Latin  small  g  with  dot  above 

g 

XK   gcircumflex 

Latin  small  g  with  circumflex  accent 

g 

XK_ubreve 

Latin  small  u  with  breve 

a 

XK   scircumflex 

Latin  small  s  with  circumflex  accent 

s 
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Table  H-6.  LATIN4 


Keysym 

Description 

Character 

XK  kappa 

Latin  small  kappa 

XK   Rcedilla 

Latin  capital  R  with  cedilla 

$ 

XK_Itilde 

Latin  capital  I  with  tilde 

I 

XK_Lcedilla 

Latin  capital  L  with  cedilla 

L 

XK  Emacron 

Latin  capital  E  with  macron 

E 

XK_Gcedilla 

Latin  capital  G  with  cedilla 

e 

XK  Tslash 

Latin  capital  T  with  oblique  stroke 

XK_r  cedilla 

Latin  small  r  with  cedilla 

r 

XK_itilde 

Latin  small  i  with  tilde 

T 

XK_lcedilla 

Latin  small  1  with  cedilla 

1 

XK   emacron 

Latin  small  e  with  macron 

e 

XK_gacute 

Latin  small  g  with  acute  accent 

g 

XK_tslash 

Latin  small  t  with  oblique  stroke 

XK_ENG 

Lappish  capital  ENG 

XK_eng 

Lappish  small  eng 

XK  Amacron 

Latin  capital  A  with  macron 

A 

XK_Iogonek 

Latin  capital  I  with  ogonek 

I 

XK_Eabovedot 

Latin  capital  E  with  dot  above 

E 

XK_Imacron 

Latin  capital  I  with  macron 

I 

XK_Ncedilla 

Latin  capital  N  with  cedilla 

I? 

XK   Omacron 

Latin  capital  O  with  macron 

6 

XK_Kcedilla 

Latin  capital  K  with  cedilla 

K 

XKJJogonek 

Latin  capital  U  with  ogonek 

V 

XK_Utilde 

Latin  capital  U  with  tilde 

U 

XK   Umacron 

Latin  capital  U  with  macron 

u 

XK   amacron 

Latin  small  a  with  macron 

a 

XK    iogonek 

Latin  small  i  with  ogonek 

i 

XK_eabovedot 

Latin  small  e  with  dot  above 

6 

XK   imacron 

Latin  small  i  with  macron 

I 

XK_ncedilla 

Latin  small  n  with  cedilla 

p 

XK   omacron 

Latin  small  o  with  macron 

0 

XK_kcedilla 

Latin  small  k  with  cedilla 

^ 

XK_uogonek 

Latin  small  u  with  ogonek 

y 

XK_utilde 

Latin  small  u  with  tilde 

u 

XK  umacron 

Latin  small  u  with  macron 

u 
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Table  H-7.  GREEK 


Keysym 


Description 


Character 


XK_Greek_ALPHAaccent 

XK_Greek_EPSILONaccent 

XK_Greek_ETAaccent 

XK_Greek_IOTAaccent 

XK_Greek_IOTAdiaeresis 

XK_Greek_IOTAaccentdiaeresis 

XK_Greek_OMICRONaccent 

XK_Greek_UPSILONaccent 

XK_Greek_UPSILONdieresis 

XK_Greek_UPSILONaccentdieresis 

XK_Greek_OMEGAaccent 

XK_Greek_alphaaccent 

XK_Greek_epsilonaccent 

XK_Greek_etaaccent 

XK_Greek_iotaaccent 

XK_Greek_iotadieresis 

XK_Greek_iotaaccentdieresis 

XK_Greek_omicronaccent 

XK_Greek_upsilonaccent 

XK_Greek_upsilondieresis 

XK_Greek_upsilonaccentdieresis 

XK_Greek_omegaaccent 

XK_Greek_ALPHA 

XK_Greek_BETA 

XK_Greek_GAMMA 

XK_Greek_DELTA 

XK_Greek_EPSILON 

XK_Greek_ZETA 

XK_Greek_ETA 

XK_Greek_THETA 

XK_Greek_IOTA 

XK_Greek_KAPPA 

XK_Greek_LAMBDA 

XK_Greek_MU 

XK_Greek_NU 

XK_Greek_XI 

XK_Greek_OMICRON 

XK   Greek   PI 


Greek  capital  alpha  with  accent 

Greek  capital  epsilon  with  accent 

Greek  capital  eta  with  accent 

Greek  capital  iota  with  accent 

Greek  capital  iota  with  diaeresis 

Greek  capital  iota  with  accent+dieresis 

Greek  capital  omicron  with  accent 

Greek  capital  upsilon  with  accent 

Greek  capital  upsilon  with  dieresis 

Greek  capital  upsilon  with  accent-i-dieresis 

Greek  capital  omega  with  accent 

Greek  small  alpha  with  accent 

Greek  small  epsilon  with  accent 

Greek  small  eta  with  accent 

Greek  small  iota  with  accent 

Greek  small  iota  with  dieresis 

Greek  small  iota  with  accent+dieresis 

Greek  small  omicron  with  accent 

Greek  small  upsilon  with  accent 

Greek  small  upsilon  with  dieresis 

Greek  small  upsilon  with  accent+dieresis 

Greek  small  omega  with  accent 

Greek  capital  alpha 

Greek  capital  beta 

Greek  capital  gamma 

Greek  capital  delta 

Greek  capital  epsilon 

Greek  capital  zeta 

Greek  capital  eta 

Greek  capital  theta 

Greek  capital  iota 

Greek  capital  kappa 

Greek  capital  lambda 

Greek  capital  mu 

Greek  capital  nu 

Greek  capital  xi 

Greek  capital  omicron 

Greek  capital  pi 
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Table  H-7.  GREEK  (continued) 


Keysym 

Description 

Character 

XK_Greek_RHO 

Greek  capital  rho 

P 

XK_Greek_SIGMA 

Greek  capital  sigma 

I, 

XK   Greek_TAU 

Greek  capital  tau 

T 

XK   Greek    UPSILON 

Greek  capital  upsilon 

Y 

XK   Greek   PHI 

Greek  capital  phi 

<fr 

XK_Greek_CHI 

Greek  capital  chi 

X 

XK_Greek_PSI 

Greek  capital  psi 

¥ 

XK   Greek_OMEGA 

Greek  capital  omega 

n 

XK   Greek   alpha 

Greek  small  alpha 

a 

XK   Greek   beta 

Greek  small  beta 

P 

XK_Greek_gamma 

Greek  small  gamma 

Y 

XK_Greek_delta 

Greek  small  delta 

8 

XK_Greek_epsilon 

Greek  small  epsilon 

e 

XK_Greek_zeta 

Greek  small  zeta 

c 

XK_Greek_eta 

Greek  small  eta 

11 

XK   Greek    theta 

Greek  small  theta 

9 

XK   Greek    iota 

Greek  small  iota 

i 

XK_Greek_kappa 

Greek  small  kappa 

K 

XK_Greek_lambda 

Greek  small  lambda 

X 

XK_Greek_mu 

Greek  small  mu 

n 

XK_Greek_nu 

Greek  small  nu 

v 

XK   Greek    xi 

Greek  small  xi 

| 

XK   Greek    omicron 

Greek  small  omicron 

o 

XK   Greek   pi 

Greek  small  pi 

7t 

XK   Greek    rho 

Greek  small  rho 

P 

XK   Greek    sigma 

Greek  small  sigma 

O 

XK_Greek_finalsmallsigma 

Greek  small  final  small  sigma 

5 

XK_Greek_tau 

Greek  small  tau 

T 

XK_Greek_upsilon 

Greek  small  upsilon 

•o 

XK   Greek   phi 

Greek  small  phi 

4> 

XK_Greek_chi 

Greek  small  chi 

X 

XK_Greek_psi 

Greek  small  psi 

V 

XK   Greek    omega 

Greek  small  omega 

CO 

XK   Greek    switch 

Switch  to  Greek  set 
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I 

The  Cursor  Font 


A  standard  font  consisting  of  a  number  of  cursor  shapes  is  available.  This  font  is  loaded 
automatically  when  XCreateFontCursor,  the  routine  used  to  create  a  standard  cursor,  is 
called.  To  specify  a  cursor  shape  from  the  standard  font,  use  one  of  the  symbols  defined  in 
the  file  <Xll/cursorfont.h>,  by  including  it  in  your  source  code.  The  symbols  for  the  avail 
able  cursors  and  an  illustration  of  their  shapes  is  provided  here.  The  technique  used  for 
creating  a  cursor  is  described  in  Volume  One,  Section  6.6. 

You  may  notice  that  the  symbol  values  skip  the  odd  numbers;  there  are  really  two  font  char 
acters  for  each  shape  but  we  are  only  showing  you  one.  Each  odd-numbered  character  (not 
shown)  is  a  mask  that  selects  which  pixels  in  the  screen  around  the  cursor  are  modified. 

The  standard  cursor  shapes  are  shown  in  Figure  1-1.  The  mask  shapes  have  been  removed. 
Each  row  in  Figure  1-1  contains  twelve  cursor  shapes  (except  the  last  one).  Table  1-1  shows 
the  symbol  definitions  from  <Xlllcursorfont.h>  grouped  by  rows  corresponding  to  the  rows 
in  Figure  I- 1. 


JH 


t* 


* 


m 


V 


m 


* 


4 


¥? 


r 


F 


T 


Figure  1-1.  The  Standard  Cursors 
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Table  1-1.  Standard  Cursor  Symbols 


Symbol 

Value 

Symbol 

Value 

Row  1 

Row  4 

XC_X_cursor 

0 

XC_left_tee 

72 

XC  arrow 

2 

XC  left  button 

74 

XC_based  arrow  down 

4 

XC_11  angle 

76 

XC  based  arrow  up 

6 

XC_lr_angle 

78 

XCJboat 

8 

XC  man 

80 

XCJbogosity 

10 

XCjmiddlebutton 

82 

XC_bottom_left  corner 

12 

XC_mouse 

84 

XC  bottom  right  corner 

14 

XC_pencil 

86 

XC_bottom_side 

16 

XCjpirate 

88 

XC_bottom_tee 

18 

XC_plus 

90 

XC  box  spiral 

20 

XC  question  arrow 

92 

XC_center  ptr 

22 

XC_right_ptr 

94 

Row  2 

Row  5 

XC  circle 

24 

XC_right_side 

96 

XC_clock 

26 

XC_right_tee 

98 

XC  coffee  mug 

28 

XC_rightbutton 

100 

XC_cross 

30 

XC  rtl  logo 

102 

XC_cross_reverse 

32 

XC_sailboat 

104 

XC_crosshair 

34 

XC_sb_down_arrow 

106 

XC  diamond  cross 

36 

XC  sb  h  double  arrow 

108 

XC  dot 

38 

XC_sb  left  arrow 

110 

XC_dotbox 

40 

XC_sb_right  arrow 

112 

XC_double  arrow 
XC  draft  large 

42 
44 

XC_sb_up_arrow 
XC_sb_v_double  arrow 

114 
116 

XC_draft  small 

46 

XC  shuttle 

118 

Row  3 

Row  6 

XC  draped  box 

48 

XC_sizing 

120 

XC  exchange 

50 

XC_spider 

122 

XC_fleur 

52 

XC  spraycan 

124 

XC_gobbler 

54 

XC_star 

126 

XC  gumby 

56 

XC_target 

128 

XC_handl 

58 

XC_tcross 

130 

XC  hand2 
XC_heart 

60 
62 

XC_top_left_arrow 
XC_top_left  corner 

132 
134 

XC_icon 

64 

XC_top_right  corner 

136 

XC_iron  cross 
XC_left  ptr 
XC_left_side 

66 
68 

70 

XC_top_side 
XC  top  tee 
XC_trek 

138 
140 
142 

Row? 

XC_ul  angle 

144 

XC_umbrella 

146 

XC_ur  angle 

148 

XC_watch 

150 

XC_xterm 

152 

XC_num  glyphs 

154 
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The  Xmu  Library 


The  Xmu  Library  is  a  collection  of  miscellaneous  utility  functions  that  have  been  useful  in 
building  various  applications  and  Xt  toolkit  widgets.  Though  not  defined  by  any  X  consor 
tium  standard,  this  library  is  written  and  supported  by  MIT  in  the  core  distribution,  and  there 
fore  should  be  available  on  virtually  all  machines. 

This  appendix  presents  reference  pages  for  each  Xmu  function  available  in  R4.  For  a  sum 
mary  of  the  contents  of  Xmu,  see  Volume  One,  Appendix  H,  The  Xmu  Library.  For  a  list  of 
which  functions  are  available  in  R3,  see  Volume  One,  Appendix  G,  Release  Notes.  At  each 
release  the  number  and  variety  of  functions  in  this  library  has  increased  dramatically.  It  is 
worthwhile  skimming  this  appendix  to  see  what  is  available  in  R4,  even  if  you  are  familiar 
with  the  R3  Xmu  library. 

Each  group  of  Xmu  functions  designed  around  a  particular  task  has  its  own  header  file,  listed 
in  the  Synopsis  section  of  each  reference  page.  Note  that  the  location  of  the  header  files  of 
Xmu  has  changed  in  R4.  In  R3  and  earlier,  the  header  files  for  all  X  libraries  were  stored  in 
lusrlincludelXll .  In  R4,  the  header  files  for  Xmu  and  Xaw  are  located  in  subdirectories  of 
this  directory,  named  after  each  library.  In  other  words,  the  Xmu  header  files  are  now  located 
(by  default,  on  UNIX-based  systems)  in  lusrlincludelXll IXmu. 
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ACtCreat8  v__ xmu  -  Compound  Text  Functions—- 

Name 

XctCreate  —  create  a  XctData  structure  for  parsing  a  Compound  Text  string. 

Synopsis 

# include  <Xll/Xmu/Xct .h> 

XctData  XctCreate (string,  length,  flags) 

XctString  string; 

int  length; 

XctFlags  flags; 

Arguments 

string  Specifies  the  Compound  Text  string. 

length  Specifies  the  number  of  bytes  in  string. 

flags  Specifies  parsing  control  flags. 

Description 

XctCreate  creates  an  XctData  structure  for  parsing  a  Compound  Text  string.  The  string 
need  not  be  null  terminated.  The  following  flags  are  defined  to  control  parsing  of  the  string: 

XctSingleSet Segments 

This  means  that  returned  segments  should  contain  characters  from  only  one  set  (CO,  Cl, 
GL,  GR).  When  this  is  requested,  Xct Segment  is  never  returned  by  XctNextltem, 
instead  XctCOSegment,  XctClSegment,  XctGlSegment,  and  XctGRSegment  are 
returned.  CO  and  Cl  segments  are  always  returned  as  singleton  characters. 

Xct ProvideExt ens ions 

This  means  that  if  the  Compound  Text  string  is  from  a  higher  version  than  this  code  is 
implemented  to,  then  syntactically  correct  but  unknown  control  sequences  should  be 
returned  as  Xct  Ext  ens  ion  items  by  XctNextltem.  If  this  flag  is  not  set,  and  the 
Compound  Text  string  version  indicates  that  extensions  cannot  be  ignored,  then  each 
unknown  control  sequence  will  be  reported  asanXctError. 

XctAcceptCOExtensions 

This  means  that  if  the  Compound  Text  string  is  from  a  higher  version  than  this  code  is 
implemented  to,  then  unknown  CO  characters  should  be  treated  as  if  they  were  legal,  and 
returned  as  CO  characters  (regardless  of  how  XctProvideExtensions  is  set)  by  Xct 
Nextltem.  If  this  flag  is  not  set,  then  all  unknown  CO  characters  are  treated  according  to 
XctProvideExtensions. 

Xct Accept ClExt ens ions 

This  means  that  if  the  Compound  Text  string  is  from  a  higher  version  than  this  code  is 
implemented  to,  then  unknown  Cl  characters  should  be  treated  as  if  they  were  legal,  and 
returned  as  Cl  characters  (regardless  of  how  XctProvideExtensions  is  set)  by  Xct 
Nextltem.  If  this  flag  is  not  set,  then  all  unknown  Cl  characters  are  treated  according  to 
XctProvideExtensions. 


712  Xlib  Reference  Manual 


Xmu  -  Compound  Text  Functions  (continued)  XctCreate 

XctHideDirection 

This  means  that  horizontal  direction  changes  should  be  reported  as  XctHorizontal 
items  by  Xct Next  item.  If  this  flag  is  not  set,  then  direction  changes  are  not  returned  as 
items,  but  the  current  direction  is  still  maintained  and  reported  for  other  items.  The  current 
direction  is  given  as  an  enumeration,  with  the  values  XctUnspecif led,  XctLeft- 
ToRight,  and  XctRightToLef  t. 

XctFreeString 

This  means  that  XctFree  should  free  the  Compound  Text  string  that  is  passed  to  Xct 
Create.  If  this  flag  is  not  set,  the  string  is  not  freed. 

XctShiftMultiGRToGL 

This  means  that  XctNextltem  should  translate  GR  segments  on-the-fly  into  GL  seg 
ments  for  the  GR  sets:  GB23 12. 1980-1,  JISX0208. 1983-1,  and  KSC560 1.1 987-1. 

Related  Commands 

XctFree, XctNextltem,  XctReset. 
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XctFree 

"    -Xmu  -  Compound  Text  Functions— 

Name 

XctFree  —  free  an  XctData  structure. 

Synopsis 

#include  <Xll/Xmu/Xct .h> 
void  XctFree (data) 
XctData  data; 

Arguments 

da  t  a  Specifies  the  Compound  Text  structure. 

Description 

XctFree  frees  all  data  associated  with  the  XctData  structure. 

Related  Commands 

XctNextltem,  XctReset. 
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J  XctNextltem 

— Xmu  -  Compound  Text  Functions — ' 

Name 

XctNextltem  —  parse  the  next  item  in  a  Compound  Text  string. 

Synopsis 

tinclude  <Xll/Xmu/Xct .h> 
XctResult  XctNextltem (data) 
XctData  data; 

Arguments 

data  Specifies  the  Compound  Text  structure. 

Description 

XctNextltem  parses  the  next  item  in  the  Compound  Text  string.  The  return  value  indicates 
what  kind  of  item  is  returned.  The  item  itself,  it's  length,  and  the  current  contextual  state,  are 
reported  as  components  of  the  XctData  structure.  XctResult  is  an  enumeration,  with  the 
following  values: 

Xct Segment 

The  item  contains  some  mixture  of  CO,  GL,  GR,  and  Cl  characters. 

XctCOSegment 

The  item  contains  only  CO  characters. 

XctGLSegment 

The  item  contains  only  GL  characters. 

XctClSegment 

the  item  contains  only  Cl  characters. 

XctGRSegment 

the  item  contains  only  GR  characters. 

XctExtendedSegment 

The  item  contains  an  extended  segment. 

XctExtension 

The  item  is  an  unknown  extension  control  sequence. 

XctHorizontal 

The  item  indicates  a  change  in  horizontal  direction  or  depth.  The  new  direction  and  depth 
are  recorded  in  the  XctData  structure. 

XctEndOfText 

The  end  of  the  Compound  Text  string  has  been  reached. 

XctError 

The  string  contains  a  syntactic  or  semantic  error;  no  further  parsing  should  be  performed. 

Structures 

typedef  struct  { 

XctString  item;  /*  the  action  item  */ 
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XctNextltem 


(continued) 


Xmu  -  Compound  Text  Functions 


int  item_length; 
int  char_size; 

char  *encoding; 

XctHDirection  horizontal, 

int  horz_depth; 

char  *GL; 

char  *GL_encoding; 

int  GL_set_size; 

int  GL_char_size; 

char  *GR; 

char  *GR_encoding; 

int  GR_set_size; 

int  GR_char_size; 

char  *GLGR_encoding; 


/*  the  length  of  item  in  bytes  */ 

/*  the  number  of  bytes  per  character  in 

*  item,  with  zero  meaning  variable  */ 
/*  the  XLFD  encoding  name  for  item  */ 
/*  the  direction  of  item  */ 

/*  the  current  direction  nesting  depth  */ 

/*  the  "{1}  F"  string  for  the  current  GL  */ 

/*  the  XLFD  encoding  name  for  the  current  GL 

/*  94  or  96  */ 

/*  the  number  of  bytes  per  GL  character  */ 

/*  the  "{1}  F"  string  for  the  current  GR  */ 

/*  the  XLFD  encoding  name  the  for  current  GR 

/*  94  or  96  */ 

/*  the  number  of  bytes  per  GR  character  */ 

/*  the  XLFD  encoding  name  for  the  current 

*  GL+GR,    if    known    */ 


}    XctData; 

Related  Commands 

XctCreate, XctFree,  XctReset. 
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— Xmu  -  Compound  Text  Functions 


J  XctReset 


Name 

XctReset  —  reset  an  XctData  structure  for  reparsing  a  Compound  Text  string. 

Synopsis 

tfinclude  <Xll/Xmu/Xct .h> 
void  XctReset (data) 
XctData  data; 

Arguments 

data  Specifies  the  Compound  Text  structure. 

Description 

XctReset  resets  the  XctData  structure  to  reparse  the  Compound  Text  string  from  the  begin 
ning. 

Related  Commands 

XctCreate, XctFree,  Xct Next I tern. 
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XmuAddCloseDisplayHook 


•Xmu  -  CloseDisplay  Hook — 


Name 

XmuAddCloseDisplayHook  —  add  callback  function  to  be  called  when  display  connection  is 
closed. 

Synopsis 

tinclude   <Xll/Xmu/CloseHook.h> 

CloseHook  XmuAddCloseDisplayHook (display,    func,    arg) 

Display  * display; 

int  (*func)  ()  ; 

caddr_t   arg; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

func  Specifies  the  function  to  call  at  display  close. 

arg  Specifies  arbitrary  data  to  pass  to  func. 

Description 

XmuAddCloseDisplayHook  registers  a  callback  for  the  given  display.  When  the  display  is 
closed,  the  given  function  will  be  called  with  the  given  display  and  argument  as: 

(*func) (display,    arg) 

The  function  is  declared  to  return  int  even  though  the  value  is  ignored,  because  some  com 
pilers  have  problems  with  functions  returning  void. 

This  routine  returns  NULL  if  it  was  unable  to  add  the  callback,  otherwise  it  returns  an  opaque 
handle  that  can  be  used  to  remove  or  lookup  the  callback. 

Related  Commands 

XmuAddCloseDisplayHook,  XmuLookupCloseDisplayHook,  XmuRemoveClose- 
DisplayHook. 
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x  XmuAIIStandardColormaps 

— Xmu  -  Standard  Colormaps ' 

Name 

XmuAIIStandardColormaps  —  create  all  supported  standard  colormaps  and  set  standard  color- 
map  properties. 

Synopsis 

# include  <Xll/Xmu/StdCmap.h> 
Status  XmuAIIStandardColormaps  (display) 
Display  *  display; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDi splay. 

Description 

XmuAIIStandardColormaps  creates  all  of  the  appropriate  standard  colormaps  for  every 
visual  of  every  screen  on  a  given  display. 

XmuAIIStandardColormaps  defines  and  retains  as  permanent  resources  all  these  standard 
colormaps.  It  returns  zero  on  failure,  non-zero  on  success.  If  the  property  of  any  standard 
colormap  is  already  defined,  this  function  will  redefine  it. 

This  function  is  intended  to  be  used  by  window  managers  or  a  special  client  at  the  start  of  a  ses 
sion. 

The  standard  colormaps  of  a  screen  are  defined  by  properties  associated  with  the  screen's  root 
window.  The  property  names  of  standard  colormaps  are  predefined,  and  each  property  name 
except  RGB_DEFAULT_MAP  may  describe  at  most  one  colormap. 

The  standard  colormaps  are:  RGB_BEST_MAP,  RGB_RED_MAP,  RGB_GREEN_MAP, 
RGB_BLUE_MAP,  RGB_DEFAULT_MAP,  and  RGB_GRAY_MAP .  Therefore  a  screen  may  have  at 
most  6  standard  colormap  properties  defined. 

A  standard  colormap  is  associated  with  a  particular  visual  of  the  screen.  A  screen  may  have 
multiple  visuals  defined,  including  visuals  of  the  same  class  at  different  depths.  Note  that  a 
visual  ID  might  be  repeated  for  more  than  one  depth,  so  the  visual  ID  and  the  depth  of  a  visual 
identify  the  visual.  The  characteristics  of  the  visual  will  determine  which  standard  colormaps 
are  meaningful  under  that  visual,  and  will  determine  how  the  standard  colormap  is  defined. 
Because  a  standard  colormap  is  associated  with  a  specific  visual,  there  must  be  a  method  of 
determining  which  visuals  take  precedence  in  defining  standard  colormaps. 

The  method  used  here  is:  for  the  visual  of  greatest  depth,  define  all  standard  colormaps  mean 
ingful  to  that  visual  class,  according  to  this  order  of  (descending)  precedence:  DirectColor; 

Pseudocolor;  TrueColor;  and  Grayscale;  and  finally  StaticColor  and  Static- 
Gray. 

This  function  allows  success  on  a  per  screen  basis.  For  example,  if  a  map  on  screen  1  fails,  the 
maps  on  screen  0,  created  earlier,  will  remain.  However,  none  on  screen  1  will  remain.  If  a 
map  on  screen  0  fails,  none  will  remain. 
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Xmu AllStandardColormaps  (continued)  Xmu  -  Standard  Colormaps 

Related  Commands 

XmuCreateColormap,  XmuDeleteStandardColormap,  XmuGetColormap- 
Allocation,  XmuLookupStdCmp,  XmuStandardColormap,  XmuVisualStandard- 
Colormaps. 
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XmuClientWindow 

— Xmu  -Window  Utility  Functions- 
Name 

XmuClientWindow  —  find  a  window  which  has  a  WM_STATE  property. 

Synopsis 

^include   <Xll/Xmu/WinUtil .h> 

Window  XmuClientWindow  (display,    win) 

Display   *display; 

Window   win; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

win  Specifies  the  window. 

Description 

XmuClientWindow  finds  a  window,  at  or  below  the  specified  window,  which 

WM  STATE  property.  If  such  a  window  is  found,  it  is  returned,  otherwise  the  argument  window 

is  returned. 

Related  Commands 

XmuScreenOf Window, XmuUpdateMapHints. 
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XmuComparelSOLatinl 


•Xmu  -  Character  Set  Functions- 


Name 

XmuComparelSOLatinl  —  compare  and  determine  order  of  two  strings,  ignoring  case. 

Synopsis 

#include  <Xll/Xmu/CharSet .h> 
int  XmuComparelSOLatinl (first ,  second) 
char  * first f  *  second; 

Arguments 

f i  rst  Specifies  a  string  to  compare. 

second  Specifies  a  string  to  compare. 

Description 

XmuComparelSOLatinl  compares  two  NULL  terminated  Latin- 1  strings,  ignoring  case  dif 
ferences,  and  returns  an  integer  greater  than,  equal  to,  or  less  than  zero,  according  to  whether 
first  is  lexicographically  greater  than,  equal  to,  or  less  than  second.  The  two  strings  are 
assumed  to  be  encoded  using  ISO  8859-1  (Latin- 1). 

Related  Commands 

XmuCopylSOLatinlLowered, XmuCopylSOLatinlUppered, XmuLookup. 
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/          XmuCopylSOLatim  Lowered 

— Xmu  -  Character  Set  Functions ' 

Name 

XmuCopylSOLatinlLowered  —  copy  string,  changing  upper  case  to  lower  case. 

Synopsis 

^include  <Xll/Xmu/CharSet .h> 
void  XmuCopylSOLatinlLowered (dst ,  src) 
char  *o!st,  *src; 

Arguments 

dst  Returns  the  string  copy. 


src 


Specifies  the  string  to  copy. 


Description 

XmuCopylSOLatinlLowered  copies  a  null  terminated  string  from  src  to  dst 

the  NULL),  changing  all  Latin- 1  upper-case  letters  to  lower-case.  The  string  is  assumed  to  be 

encoded  using  ISO  8859-1  (Latin- 1). 

Related  Commands 

XmuComparelSOLatinl, XmuCopylSOLatinlUppered,  XmuLookup. 
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XmuCopylSOLatinl  Uppered 


•Xmu  -  Character  Set  Functions — 


Name 

XmuCopylSOLatinlUppered  —  copy  string,  changing  lower  case  to  upper  case. 

Synopsis 

# include  <Xll/Xmu/CharSet .h> 
void  XmuCopylSOLatinlUppered (dst f  src) 
char  *dst,  *src; 

Arguments 

dst  Returns  the  string  copy. 

src  Specifies  the  string  to  copy. 

Description 

XmuCopylSOLatinlUppered  copies  a  null  terminated  string  from  src  to  dst  (including 
the  NULL),  changing  all  Latin- 1  lower-case  letters  to  upper-case.  The  string  is  assumed  to  be 
encoded  using  ISO  8859-1  (Latin- 1). 

Related  Commands 

XmuComparelSOLatinl, XmuCopylSOLatinlLowered, XmuLookup. 
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.  XmuCreateColormap 

— Xmu  -  Standard  Colormaps ' 

Name 

XmuCreateColormap  —  create  a  standard  colormap  from  information  in  an  XStandard- 
Colormap  structure. 

Synopsis 

#include  <Xll/Xmu/StdCmap.h> 

Status  XmuCreateColormap (display,  colormap) 

Display  * display ; 

XStandardColormap  * colormap; 

Arguments 

display  Specifies  the  connection  under  which  the  map  is  created. 

col  ormap         Specifies  the  map  to  be  created. 

Description 

XmuCreateColormap  creates  any  one  colormap  which  is  described  by  an  XStandard 
Colormap  structure. 

XmuCreateColormap  returns  zero  on  failure,  and  non-zero  on  success.  The  base_pixel 
field  of  the  XStandardColormap  structure  is  set  on  success.  Resources  created  by  this 
function  are  not  made  permanent.  No  argument  error  checking  is  provided;  use  at  your  own 
risk. 

All  colormaps  are  created  with  read-only  allocations,  with  the  exception  of  read-only  alloca 
tions  of  colors  which  fail  to  return  the  expected  pixel  value,  and  these  are  individually  defined 
as  read/write  allocations.  This  is  done  so  that  all  the  cells  defined  in  the  colormap  are  contigu 
ous,  for  use  in  image  processing.  This  typically  happens  with  White  and  Black  in  the  default 
map. 

Colormaps  of  static  visuals  are  considered  to  be  successfully  created  if  the  map  of  the  static 
visual  matches  the  definition  given  in  the  standard  colormap  structure. 

Related  Commands 

XmuAllStandardColormaps,  XmuDeleteStandardColormap,  XmuGet- 
ColormapAllocation, XmuLookupStdCmp,  XmuStandardColormap, XmuVisual- 
StandardColormaps. 
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XmuCreatePixmapFromBitmap     \ Xmu_  Graphics  Functions_ 

Name 

XmuCreatePixmapFromBitmap  —  create  multi-plane  pixmap  and  copy  data  from  one-plane 

pixmap. 

Synopsis 

#include  <Xll/Xmu/Drawing.h> 

Pixmap  XmuCreatePixmapFromBitmap  (display,  d,  bitmap,  width, 
height,  depth,  fore,  back) 

Display  *  display; 

Drawable  d; 

Pixmap  bitmap; 

unsigned  int  width,  height; 

unsigned  int  depth; 

unsigned  long  fore,  back; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD  i sp  1  ay. 

d  Specifies  the  screen  the  pixmap  is  created  on. 

bi  tmap  Specifies  the  bitmap  source. 

wi  dth  Specifies  the  width  of  the  pixmap. 

height  Specifies  the  height  of  the  pixmap. 

depth  Specifies  the  depth  of  the  pixmap. 

fore  Specifies  the  foreground  pixel  value. 

back  Specifies  the  background  pixel  value. 

Description 

XmuCreatePixmapFromBitmap  creates  a  pixmap  of  the  specified  width,  height,  and  depth, 
on  the  same  screen  as  the  specified  drawable,  and  then  performs  an  XCopyPlane  from  the 
specified  bitmap  to  the  pixmap,  using  the  specified  foreground  and  background  pixel  values. 
The  created  pixmap  is  returned.  The  original  bitmap  is  not  destroyed. 

Related  Commands 

XmuCreateStippledPixmap,  XmuDrawLogo,  XmuDrawRoundedRectangle,  Xmu- 
FillRoundedRectangle,  XmuLocateBitmapFile,  XmuReadBitmapData,  Xmu- 
ReadBitmapDataFromFile, XmuRe lease StippledPixmap. 
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— Xmu  -  Graphics  Functions- 


XmuCreateStippledPixmap 


Name 


XmuCreateStippledPixmap  —  create  two  pixel  by  two  pixel  gray  pixmap. 


Synopsis 

#include  <Xll/Xmu/Drawing.h> 

Pixmap  XmuCreateStippledPixmap  (screen 

Screen  *  screen; 

Pixel  fore,  back; 

unsigned  int  depth; 


fore,  back,  depth) 


Arguments 

screen 
fore 
back 
depth 


Specifies  the  screen  the  pixmap  is  created  on. 
Specifies  the  foreground  pixel  value. 
Specifies  the  background  pixel  value. 
Specifies  the  depth  of  the  pixmap. 


Description 

XmuCreateStippledPixmap  creates  a  two  pixel  by  two  pixel  stippled  pixmap  of  specified 
depth  on  the  specified  screen.  The  pixmap  is  cached  so  that  multiple  requests  share  the  same 
pixmap.  The  pixmap  should  be  freed  with  XmuReleaseStippledPixmap  to  maintain  cor 
rect  reference  counts. 

Related  Commands 

XmuCreatePixmapFromBitmap,  XmuDrawLogo,  XmuDrawRoundedRectangle, 
XmuFillRoundedRectangle,  XmuLocateBitmapFile,  XmuReadBitmapData, 
XmuReadBitmapDataFromFile, XmuReleaseStippledPixmap. 
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_Xmu  -  Cursor  Utl.lty  Functions- 
Name 

XmuCursorNameToIndex  —  return  index  in  cursor  font  given  string  name. 

Synopsis 

#include  <Xll/Xmu/CurUtil .h> 
int  XmuCursorNameToIndex  (name) 
char  *name; 

Arguments 

name  Specifies  the  name  of  the  cursor. 

Description 

XmuCursorNameToIndex  takes  the  name  of  a  standard  cursor  and  returns  its  index  in  the 
standard  cursor  font  The  cursor  names  are  formed  by  removing  the  xc_  prefix  from  the  cur 
sor  defines  listed  in  Appendix  I,  The  Cursor  Font. 
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_T  XmuDQAddDisplay 

— Xmu  -  Display  Queue  Functions ' 

Name 

XmuDQAddDisplay  —  add  a  display  connection  to  a  display  queue. 

Synopsis 

#include  <Xll/Xmu/DisplayQue .h> 

XmuDisplayQueueEntry  * XmuDQAddDisplay (q,  display,  data) 

XmuDisplayQueue  *g; 

Display   *display; 

caddr_t   data; 

Arguments 

q  Specifies  the  queue. 

display  Specifies  the  display  connection  to  add. 

data  Specifies  private  data  for  the  free  callback  function. 

Description 

XmuDQAddDisplay  adds  the  specified  display  to  the  queue.  If  successful,  the  queue  entry  is 
returned,  otherwise  NULL  is  returned.  The  data  value  is  simply  stored  in  the  queue  entry  for  use 
by  the  queue's  free  callback.  This  function  does  not  attempt  to  prevent  duplicate  entries  in  the 
queue;  the  caller  should  use  XmuDQLookupDisplay  to  determine  if  a  display  has  already 
been  added  to  a  queue. 

Related  Commands 

XmuDQCreate,  XmuDQDestroy,  XmuDQLookupDisplay,  XmuDQNDisplays,  Xmu- 
DQRemoveDi splay. 
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XmuDQCreate  V — Xmu  -  Display  Queue  Functions- 

Name 

XmuDQCreate  —  creates  an  empty  display  queue. 

Synopsis 

#include  <Xll/Xmu/DisplayQue .h> 

XmuDisplayQueue  *XmuDQCreate (closefunc,  freefunc,  data) 

int (* closefunc)  ()  ; 

int (* freefunc)  () ; 

caddr_t  data; 

Arguments 

closefunc       Specifies  the  close  function. 

freefunc         Specifies  the  free  function. 

data  Specifies  private  data  for  the  functions. 

Description 

XmuDQCreate  creates  and  returns  an  empty  XmuDisplayQueue  (which  is  really  just  a  set 
of  displays,  but  is  called  a  queue  for  historical  reasons).  The  queue  is  initially  empty,  but  dis 
plays  can  be  added  using  XmuAddDisplay.  The  data  value  is  simply  stored  in  the  queue  for 
use  by  the  display  close  and  free  callbacks.  Whenever  a  display  in  the  queue  is  closed  using 
XCloseDisplay,  the  display  close  callback  (if  non-NULL)  is  called  with  the  queue  and  the 
display's  XmuDisplayQueueEntry  as  follows: 

(*closefunc) (queue,    entry) 

The  free  callback  (if  non-NULL)  is  called  whenever  the  last  display  in  the  queue  is  closed,  as 
follows: 

(*freefunc) (queue) 
The  application  is  responsible  for  actually  freeing  the  queue,  by  calling  XmuDQDestroy. 

Related  Commands 

XmuDQAddDisplay,  XmuDQDestroy,  XmuDQLookupDisplay,  XmuDQNDisplays, 
XmuDQRemoveDi splay. 
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/  XmuDQDestroy 

— Xmu  -  Display  Queue  Functions ' 

Name 

XmuDQDestroy  —  destroy  a  display  queue,  and  optionally  call  callbacks. 

Synopsis 

tfinclude  <Xll/Xmu/DisplayQue .h> 
Bool  XmuDQDestroy (q,  docallbacks) 

XmuDisplayQueue  *q; 

Bool  docallbacks; 

Arguments 

q  Specifies  the  queue  to  destroy. 

docallbacks  Specifies  whether  the  close  callback  functions  should  be  called. 

Description 

XmuDQDestroy  releases  all  memory  associated  with  the  specified  queue.  If  docallbacks 
is  True,  then  the  queue's  close  callback  (if  non-NULL)  is  first  called  for  each  display  in  the 
queue,  even  though  xcioseDisplay  is  not  called  on  the  display. 

Related  Commands 

XmuDQAddDisplay,  XmuDQCreate,  XmuDQLookupDisplay,  XmuDQNDisplays, 
XmuDQRemoveDisplay. 
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XmuDQLookupDisplay 


•Xmu  -  Display  Queue  Functions- 


Name 

XmuDQLookupDisplay  —  determine  display  queue  entry  for  specified  display  connection. 

Synopsis 

#include  <Xll/Xmu/DisplayQue .h> 
XmuDisplayQueueEntry  *XmuDQLookupDisplay (q,  display) 

XmuDisplayQueue  *q; 

Display   *display; 

Arguments 

q  Specifies  the  queue. 

di  spl  ay  Specifies  the  display  to  lookup. 

Description 

XmuDQLookupDisplay  returns  the  queue  entry  for  the  specified  display,  or  NULL  if  the  dis 
play  is  not  in  the  queue. 

Related  Commands 

XmuDQAddDisplay,  XmuDQCreate,  XmuDQDestroy,  XmuDQNDisplays,  Xmu- 
DQRemoveDi splay. 
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/  XmuDQNDisplays 

— Xmu  -  Display  Queue  Functions '  * 

Name 

XmuDQNDisplays  —  return  the  number  of  display  connections  in  a  display  queue. 

Synopsis 

#include  <Xll/Xmu/DisplayQue .h> 
XmuDQNDisplays  (q) 

Description 

XmuDQNDisplays  returns  the  number  of  displays  in  the  specified  queue. 

Related  Commands 

XmuDQAddDi splay, XmuDQCreate,  XmuDQDestroy,  XmuDQLookupDisplay,  Xmu- 
DQRemoveDisplay. 
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XmuDQRemoveDisplay 


Xmu  -  Display  Queue  Functions  — 


Name 

XmuDQRemoveDisplay  —  remove  a  display  connection  from  a  display  queue. 

Synopsis 

#include  <Xll/Xmu/DisplayQue .h> 
Bool  XmuDQRemoveDisplay  (q,  display) 

XmuDisplayQueue  *g; 

Display   ^display; 

Arguments 

g  Specifies  the  queue. 

di  spl  ay  Specifies  the  display  to  remove. 

Description 

XmuDQNDisplays  removes  the  specified  display  connection  from  the  specified  queue.  No 
callbacks  are  performed.  If  the  display  is  not  found  in  the  queue,  False  is  returned,  otherwise 
True  is  returned. 

Related  Commands 

XmuDQAddDisplay,  XmuDQCreate,  XmuDQDestroy,  XmuDQLookupDisplay,  Xmu 
DQNDisplays. 
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— Xmu  -  Standard  Colormaps- 


XmuDeieteStandardColormap 


Name 

XmuDeleteStandardColormap  —  remove  any  standard  colormap  property. 

Synopsis 

void  XmuDeleteStandardColormap  (  display,  screen ,  property) 
Display  *display; 
int  screen ; 
Atom  property; 


Arguments 

display 

scree/1 
property 


Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 
Specifies  the  screen  of  the  display. 
Specifies  the  standard  colormap  property. 


Description 

XmuDeleteStandardColormap  will  remove  the  specified  property  from  the  specified 
screen,  releasing  any  resources  used  by  the  colormap(s)  of  the  property,  if  possible. 

Related  Commands 

XmuAllStandardColormaps,  XmuCreateColormap,  XmuGe t Colormap - 
Allocation, XmuLookupStdCmp,  XmuStandardColormap,  XmuVisualStandard- 
Colormaps. 
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XmuDrawLogo 


•Xmu  -  Graphics  Functions — 


Name 

XmuDrawLogo  —  draws  the  standard  X  logo. 

Synopsis 

#include  <Xll/Xmu/Drawing.h> 

XmuDrawLogo (display,  drawable,  gcFore,  gcBack,  x,  y,  width, 
height) 

Display  *display; 

Drawable   drawable; 

GC   grcFore,    gcBack; 

int   xr    y; 

unsigned  int  width,  height; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

dra  wabl  e  Specifies  the  drawable. 

gcFore  Specifies  the  foreground  GC. 

gcBack  Specifies  the  background  GC. 

x  Specifies  the  upper  left  x  coordinate, 

y  Specifies  the  upper  left  y  coordinate. 

width  Specifies  the  logo  width. 

height  Specifies  the  logo  height 

Description 

XmuDrawLogo  draws  the  "official"  X  Window  System  logo.  The  bounding  box  of  the  logo 
in  the  drawable  is  given  by  x,  y,  width,  and  height .  The  logo  itself  is  filled  using  gcFore, 
and  the  rest  of  the  rectangle  is  filled  using  gcBack. 

Related  Commands 

XmuCreatePixmapFromBitmap,  XmuCreateStippledPixmap,  XmuDraw- 
RoundedRectangle,  XmuFillRoundedRectangle,  XmuLocateBitmapFile, Xmu- 
ReadBitmapData,  XmuReadBitmapDataFromFile,  XmuReleaseStippled- 
Pixmap. 
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— Xmu  -  Graphics  Functions- 


XmuDrawRoundedRectangle 


Name 

XmuDrawRoundedRectangle  —  draws  a  rectangle  with  rounded  corners. 

Synopsis 

#include  <Xll/Xmu/Drawing.h> 

void  XmuDrawRoundedRectangle  (display,  draw,  gc,  x,  y,  wr  h,  ewf 
eh) 

Display  *  display; 

Drawable  draw; 

GC   gc; 

int   x,    y,    w,    hf    ew,    eh; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

draw  Specifies  the  drawable. 

gc  Specifies  the  GC. 

x  Specifies  the  upper  left  x  coordinate, 

y  Specifies  the  upper  left  y  coordinate. 

w  Specifies  the  rectangle  width. 

h  Specifies  the  rectangle  height 

ew  Specifies  the  corner  width. 

eh  Specifies  the  corner  height 

Description 

XmuDrawRoundedRectangle  draws  a  rounded  rectangle,  where  x,  y,  w,  h  are  the  dimen 
sions  of  the  overall  rectangle,  and  ew  and  eh  are  the  sizes  of  a  bounding  box  that  the  corners 
are  drawn  inside  of;  ew  should  be  no  more  than  half  of  w,  and  eh  should  be  no  more  than  half 
of  h.  The  current  GC  line  attributes  control  all  attributes  of  the  line. 

Related  Commands 

XmuCreatePixmapFromBitmap,  XmuCreateStippledPixmap,  XmuDrawLogo, 
XmuFillRoundedRectangle,  XmuLocateBitmapFile,  XmuReadBitmapData, 
XmuReadBitmapDataFromFile,  XmuReleaseStippledPixmap. 
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XmuFillRoundedRectangle 


•Xmu  -  Graphics  Functions — 


Name 

XmuFillRoundedRectangle  —  fill  a  rectangle  with  rounded  corners. 

Synopsis 

#include  <Xll/Xmu/Drawing.h> 

void  XmuFillRoundedRectangle  (display,  draw,  gc,  x,  y,  w,  h,  ew , 
eh) 

Display  *display; 

Drawable  draw; 

GC   gc; 

int   x,    y,    v,    h,    ew,    eh; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

draw  Specifies  the  drawable. 

gc  Specifies  the  GC. 

x  Specifies  the  upper  left  x  coordinate, 

y  Specifies  the  upper  left  y  coordinate. 

w  Specifies  the  rectangle  width. 

h  Specifies  the  rectangle  height 

ew  Specifies  the  corner  width. 

eh  Specifies  the  corner  height 

Description 

XmuFillRoundedRectangle  draws  a  filled  rounded  rectangle,  where  x,  y,  w,  h  are  the 
dimensions  of  the  overall  rectangle,  and  e  w  and  eh  are  the  sizes  of  a  bounding  box  that  the  cor 
ners  are  drawn  inside  of;  ew  should  be  no  more  than  half  of  w,  and  eh  should  be  no  more  than 
half  of  h.  The  current  GC  fill  settings  control  all  attributes  of  the  fill  contents. 

Related  Commands 

XmuCreatePixmapFromBitmap,  XmuCreateStippledPixmap,  XmuDrawLogo, 
XmuDrawRoundedRectangle,  XmuLocateBitmapFile,  XmuReadBitmapData, 
XmuReadBitmapDataFromFile.XmuReleaseStippledPixmap. 
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—  Xmu  -  Atom  Functions 


J  XmuGetAtomName 


Name 

XmuGetAtomName  —  returns  the  property  name  string  corresponding  to  the  specified  atom. 

Synopsis 

tinclude  <X11 /Xmu/ Atoms .h> 
char  *  XmuGetAtomName  (  d,  atom) 

Display  *d; 

Atom  atom; 

Arguments 

d  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDi splay. 

a  t  om  Specifies  the  atom  whose  name  is  desired. 

Description 

XmuGetAtomName  returns  the  property  name  string  corresponding  to  the  specified  atom.  The 
result  is  cached,  such  that  subsequent  requests  do  not  cause  another  round-trip  to  the  server.  If 
the  atom  is  zero,  XmuGetAtomName  returns  "(BadAtom)". 

Related  Commands 

XmuInternAtom,  XmuInternStrings,  XmuMakeAtom,  XmuNameof  Atom. 


Xlib  Reference  Manual  739 


XmuGetColormapAllocation 


•Xmu  -  Standard  Colormaps— 


Name 

XmuGetColormapAllocation  —  determine  best  allocation  of  reds,  greens,  and  blues  in  a  stan 
dard  colormap. 

Synopsis 

^include  <Xll/Xmu/StdCmap.h> 

Status  XmuGetColormapAllocation (  vinfo,  property,  red_max , 
green_max,  blue_max) 

XVisuallnfo  * vinfo; 

Atom  property; 

unsigned  long  *red_max,  *green_maxf  *blue_max; 

Arguments 

vinfo  Specifies  visual  information  for  a  chosen  visual. 

property  Specifies  one  of  the  standard  colormap  property  names. 

red_max  Returns  maximum  red  value. 

green_max  Returns  maximum  green  value. 

bl  ue_max  Returns  maximum  blue  value. 

Description 

XmuGetColormapAllocation  determines  the  best  allocation  of  reds,  greens,  and  blues  in 
a  standard  colormap. 

XmuGetColormapAllocation  returns  zero  on  failure,  non-zero  on  success.  It  is  assumed 
that  the  visual  is  appropriate  for  the  colormap  property. 

Related  Commands 

XmuAllStandardColormaps,  XmuCreateColormap,  XmuDeleteStandard- 
Colormap,  XmuLookupStdCmp,  XmuStandardColormap,  XmuVisualStandard- 
Colormaps. 
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-x™  -system  u,i,,«y  Functions^  XmuGetHostname 

Name 

XmuGetHostname  —  operating  system  independent  routine  to  get  machine  name. 

Synopsis 

#include  <Xll/Xmu/SysUtil .h> 
int  XmuGetHostname  (buf ,  maxlen) 

char  *buf; 

int  maxlen; 

Arguments 

buf  Returns  the  host  name. 

maxl  en  Specifies  the  length  of  buf . 

Description 

XmuGetHostname  stores  the  null  terminated  name  of  the  local  host  in  buf,  and  returns  the 
length  of  the  name.  This  function  hides  operating  system  differences,  such  as  whether  to  call 
gethostname  or  uname. 
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XmulnternAtom  X Xmu  _  Atom  Functions  _ 

Name 

XmulnternAtom  —  get  an  atom  from  the  server  and  load  it  into  an  AtomPt  r. 

Synopsis 

Atom  XmulnternAtom  (d,    atom_jptr) 
Display   *d; 
AtomPtr   atom_ptr; 

Arguments 

d  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

atom_ptr         Specifies  the  AtomPtr. 

Description 

XmulnternAtom  gets  an  atom  from  the  server  (for  the  string  stored  in  AtomPtr)  and  stores 
the  atom  in  the  specified  AtomPtr.  The  atom  is  cached  such  that  subsequent  requests  do  not 
cause  another  round-trip  to  the  server. 

Related  Commands 

XmuGetAtomName,  XmuInternSt rings,  XmuMakeAtom,  XmuNameof  Atom. 
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— Xmu  -  Atom  Function 


XmulnternStrings 


Name 


XmulnternStrings  —  get  the  atoms  for  several  property  name  strings. 


Synopsis 

tfinclude   <Xll/Xmu/ Atoms .h> 
void  XmulnternStrings (d,    names , 

Display   *d; 

String  * names; 

Cardinal  count; 

Atom  * atoms; 


count r  atoms) 


Arguments 


d 

names 
count 
atoms 


Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 
Specifies  the  strings  to  intern. 
Specifies  the  number  of  strings. 
Returns  the  list  of  Atoms  value. 


Description 

XmulnternStrings  converts  a  list  of  property  name  strings  into  a  list  of  atoms,  possibly  by 
querying  the  server.  The  results  are  cached,  such  that  subsequent  requests  do  not  cause  further 
round-trips  to  the  server.  The  caller  is  responsible  for  preallocating  the  array  of  atoms. 

Related  Commands 

XmuGetAtomName,  XmuInternAtom,  XmuMakeAtom,  XmuNameof  Atom. 
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XmuLocateBitmapFile  V Xmu  _  Graphics  Functions- 

Name 

XmuLocateBitmapFUe  —  creates  a  one-plane  pixmap  from  a  bitmap  file  in  a  standard  location. 
Synopsis 

#include  <Xll/Xmu/Drawing.h> 

XmuLocateBitmapFile (screen,  name,  srcname,  srcnamelen,  widthp, 
heigh tp,  xhotp,  yhotp) 

Screen  * screen; 

char  *name; 

char   * srcname; 

int   srcnamelen; 

int    *widthp,    *heightp,    *xhotp,    *yhotp; 

Arguments 

name  Specifies  the  file  to  read  from. 

srcname  Returns  the  full  filename  of  the  bitmap. 

srcn  amel  en  Specifies  the  length  of  the  srcname  buffer. 

wi  dth  Returns  the  width  of  the  bitmap. 

height  Returns  the  height  of  the  bitmap. 

xhotp  Returns  the  x  coordinate  of  the  hotspot. 

yhotp  Returns  the  y  coordinate  of  the  hotspot. 

Description 

XmuLocateBitmapFile  reads  a  file  in  standard  bitmap  file  format,  using  XReadBitmap- 
File,  and  returns  the  created  bitmap.  The  filename  may  be  absolute,  or  relative  to  the  global 
resource  named  bitmapFilePath  with  class  BitmapFilePath.  If  the  resource  is  not 
defined,  the  default  value  is  the  build  symbol  BITMAPDIR,  which  is  typically 
lusrlindudelX 11  /bitmaps.  If  srcnamelen  is  greater  than  zero  and  srcname  is  not  NULL,  the 
null  terminated  filename  will  be  copied  into  srcname.  The  size  and  hotspot  of  the  bitmap  are 
also  returned. 

Related  Commands 

XmuCreatePixmapFromBitmap,  XmuCreateStippledPixmap,  XmuDrawLogo, 
XmuDrawRoundedRectangle,  XmuFillRoundedRectangle,  XmuReadBitmap- 
Data,  XmuReadBitmapDataFromFile,  XmuReleaseStippledPixmap. 
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— Xmu  -  Character  Set  Functions- 


XmuLookup* 


Name 

XmuLookup*  —  translate  a  key  event  into  a  keysym  and  string,  using  various  keysym  sets. 

Synopsis 

#include  <Xll/Xmu/CharSet  .h> 

int  XmuLookupLatinl  (event  ,  buffer,  nbytes  ,  keysym,  status) 
int  XmuLookupLatin2  (event  ,  buffer,  nbytes,  keysym,  status) 
int  XmuLookupLatin3  (event,  buffer,  nbytes,  keysym,  status) 
int  XmuLookupLatin4  (event  ,  buffer,  nbytes,  keysym,  status) 
int  XmuLookupKana  (  event  ,  buffer,  nbytes,  keysym,  status) 
int  XmuLookup  JISX02  01  (event  ,  buffer,  nbytes,  keysym,  status) 
int  XmuLookupArabic  (event  ,  buffer,  nbytes,  keysym,  status) 
int  XmuLookupCyrillic  (  eve/it  ,  buffer,  nbytes,  keysym,  status) 
int  XmuLookupGreek  (  event  ,  buffer,  nbytes,  keysym,  status) 
int  XmuLookupHebrew  (  event  ,  buffer,  nbytes,  keysym,  status) 
int  XmuLookupAPL  (  event  ,  buffer,  nbytes,  keysym,  status) 

XKeyE  vent  *  even  t  ; 

char  *buffer; 

int  nbytes; 

KeySym  *  keysym; 

XComposeStatus  *status; 


Arguments 

event 

buffer 
nbytes 
keysym 
status 


Specifies  the  key  event 
Returns  the  translated  characters. 
Specifies  the  length  of  the  buffer. 
Returns  the  computed  KeySym,  or  None. 
Specifies  or  returns  the  compose  state. 


Description 

These  functions  translate  a  key  event  into  a  keysym  and  string,  using  a  keysym  set  other  than 
Latin-  1,  as  shown  in  the  following  table. 
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XmuLookup* 

Function 


(continued) 


Xmu  -  Character  Set  Functions 


XmuLookupLatinl 

XmuLookupLa t  in2 
XmuLookupLat  in3 
XmuLookupLa tin 4 
XmuLookupKana 


XmuLookup JISXO 2  0 1 

XmuLookupArabic 

XmuLookupCyrillic 

XmuLookupGreek 

XmuLookupHebrew 

XmuLookup APL 


Converts  To 


Latin- 1  (ISO  8859-1),  or  ASCII  control  (Synonym 

for  XLookupString) 

Latin-2  (ISO  8859-2),  or  ASCII  control. 

Latin-3  (ISO  8859-3),  or  ASCII  control. 

Latin-4  (ISO  8859^),  or  ASCII  control. 

Latin- 1   (ISO  8859-1)  and  ASCII  control  in  the 

Graphics  Left  half  (values  0  to  127),  and  Katakana 

in  the  Graphics  Right  half  (values  128  to  255),  using 

the  values  from  JIS  X201-1976. 

JIS  X0201-1976  encoding,  including  ASCII  control. 

Latin/Arabic  (ISO  8859-6),  or  ASCII  control. 

Latin/Cyrillic  (ISO  8859-5),  or  ASCII  control. 

Latin/Greek  (ISO  8859-7),  or  ASCII  control. 

Latin/Hebrew  (ISO  8859-8),  or  ASCII  control  string. 

APL  string 


XmuLookupLatinl  is  identical  to  XLookupString,  and  exists  only  for  naming  symmetry 
with  other  functions  covered  on  this  page. 

Related  Commands 

XmuComparelSOLatinl,   XmuCopylSOLatinlLowered,   XmuCopylSOLatinl- 
Uppered. 
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— Xmu  -  CloseDisplay  Hook- 


XmuLookupCloseDisplayHook 


Name 


XmuLookupCloseDisplayHook  —  get  currently  registered  close  display  callback  function. 


Synopsis 

#include  <Xll/Xmu/CloseHook.h> 

Bool  XmuLookupCloseDisplayHook (  display,  handle, 

Display  * display ; 

CloseHook  handle; 

int  (*func)  ()  ; 

caddr  t    arg; 


func,    arg) 


Arguments 

isplay 

handle 

func 

arg 


Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 
Specifies  the  callback  by  ID,  or  NULL. 
Specifies  the  callback  by  function. 
Specifies  the  function  data  to  match. 


Description 

XmuLookupCloseDisplayHook  determines  if  a  callback  is  registered.  If  handle  is  not 
NULL,  it  specifies  the  callback  to  look  for,  and  the  func  and  arg  parameters  are  ignored.  If 
handle  is  NULL,  the  function  will  look  for  any  callback  that  matches  the  specified  func  and 
arg.  This  function  returns  True  if  a  matching  callback  exists,  or  otherwise  False. 

Related  Commands 

XmuAddCloseDisplayHook, XmuRemoveCloseDisplayHook. 
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Xmu  -  Standard  Colormaps- 

Name 

XmuLookupStandardColormap  —  create  a  standard  colormap  if  not  already  created. 

Synopsis 

#include   <Xll/Xmu/StdCmap.h> 

XmuLookupStandardColormap (display,    screen,    visualid,    depth, 
property,    replace,    retain) 

Display   *display; 

int   screen ; 

VisuallD   visualid; 

unsigned   int   depth; 

Atom  property; 

Bool   replace; 

Bool    retain; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDisplay. 

screen  Specifies  the  screen  of  the  display. 

visualid  Specifies  the  visual  type. 

depth  Specifies  the  visual  depth. 

property  Specifies  the  standard  colormap  property, 

repl ace  Specifies  whether  or  not  to  replace, 

retain  Specifies  whether  or  not  to  retain. 

Description 

XmuLookupStandardColormap  creates  a  standard  colormap  if  one  does  not  currently 
exist,  or  replaces  the  currently  existing  standard  colormap. 

Given  a  screen,  a  visual,  and  a  property,  this  function  will  determine  the  best  allocation  for  the 
property  under  the  specified  visual,  and  determine  whether  to  create  a  new  colormap  or  to  use 
the  default  colormap  of  the  screen. 

If  replace  is  True,  any  previous  definition  of  the  property  will  be  replaced.  If  retain  is 
True,  the  property  and  the  colormap  will  be  made  permanent  for  the  duration  of  the  server  ses 
sion.  However,  pre-existing  property  definitions  which  are  not  replaced  cannot  be  made  perma 
nent  by  a  call  to  this  function;  a  request  to  retain  resources  pertains  to  newly  created  resources. 

XmuLookupStandardColormap  returns  zero  on  failure,  non-zero  on  success.  A  request  to 
create  a  standard  colormap  upon  a  visual  which  cannot  support  such  a  map  is  considered  a  fail 
ure.  An  example  of  this  would  be  requesting  any  standard  colormap  property  on  a  mono 
chrome  visual,  or,  requesting  an  RGB_BEST_MAP  on  a  display  whose  colormap  size  is  16. 
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Xmu  -  Standard  Colormaps 


(continued)      XmuLookupStandardColormap 


Related  Commands 

XmuAllStandardColormaps,  XmuCreateColormap,  XmuDeleteStandard- 
Colormap,  XmuGetColormapAllocation,  XmuStandardColormap,  XmuVisual- 
StandardColormaps. 
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XmuMakeAtom  V. 

v Xmu  -  Atom  Functions— 

Name 

XmuMakeAtom  —  create  AtomPtr  to  hold  atom  list  for  a  property  name  string. 

Synopsis 

#include  <X1 I/ Xmu /Atoms .h> 
AtomPtr  XmuMakeAtom (name) 
char*  name; 

Arguments 

name  Specifies  the  atom  name. 

Description 

XmuMakeAtom  creates  and  initializes  an  AtomPtr,  which  is  an  opaque  object  that  contains  a 
property  name  string  and  a  list  of  atoms  for  that  string— one  for  each  display.  Xmu  Intern- 
Atom  is  used  to  fill  in  the  atom  for  each  display. 

Related  Commands 

XmuGetAtomName,  XmuInternAtom,  XmuInternStrings,  XmuNameof  Atom. 
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j  XmuNameOfAtom 

— Xmu  -  Atom  Functions ' 

Name 

XmuNameOfAtom  —  return  property  name  string  represented  by  an  AtomPt  r. 

Synopsis 

tinclude  <X1 I/ Xmu /Atoms .h> 
char  *XmuNameOfAtom(atom_jDtr) 
AtomPtr  atom_ptr; 

Arguments 

atomjptr         Specifies  the  AtomPtr. 

Description 

XmuNameOfAtom  returns  the  property  name  string  represented  by  the  specified  AtomPtr. 

Related  Commands 

XmuGetAtomName,  XmuInternAtom,  XmuInternStrings,  XmuMakeAtom. 
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XmuPrintDefaultErrorMessage     \ 


•Xmu  -  Error  Handler— 


Name 

XmuPrintDefaultErrorMessage  —  print  the  standard  protocol  error  message. 

Synopsis 

#include  <Xll/Xmu/Error .h> 

int  XmuPrintDefaultErrorMessage  (display,  event,  fp) 

Display  *display; 

XErrorEvent    * event; 

FILE    *fp; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XQpenDi splay. 

event  Specifies  the  error  event  whose  contents  will  be  printed. 

fp  Specifies  where  to  print  the  error  message. 

Description 

XmuPrintDefaultErrorMessage  prints  an  error  message,  equivalent  to  Xlib's  default 
error  message  for  protocol  errors.  It  returns  a  non-zero  value  if  the  caller  should  consider  exit 
ing,  otherwise  it  returns  zero.  This  function  can  be  used  when  you  need  to  write  your  own  error 
handler,  but  need  to  print  out  an  error  from  within  that  handler. 

Related  Commands 

XmuSimpleErrorHandler. 
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.  XmuReadBitmapData 

— Xmu  -  Graphics  Functions ' 

Name 

XmuReadBitmapData  —  read  and  check  bitmap  data  from  any  stream  source. 

Synopsis 

^include  <Xll/Xmu/Drawing.h> 

int  XmuReadBitmapData (fstream,  width,  height,  datap,  x_hot , 
y_hot ) 

FILE  *  fstream; 

unsigned  int  * width,  *  height; 

unsigned  char  ** datap; 

int    *x_hot,    *y_hot; 

Arguments 

stream  Specifies  the  stream  to  read  from. 

wi  dth  Returns  the  width  of  the  bitmap. 

height  Returns  the  height  of  the  bitmap. 

da  t  ap  Returns  the  parsed  bitmap  data. 

x_hot  Returns  the  x  coordinate  of  the  hotspot. 

y_hot  Returns  the  y  coordinate  of  the  hotspot. 

Description 

XmuReadBitmapData  reads  a  standard  bitmap  file  description  from  the  specified  stream,  and 
returns  the  parsed  data  in  a  format  suitable  for  passing  to  XCreatePixmapFromBitmap- 
Data.  The  return  value  of  the  function  has  the  same  meaning  as  the  return  value  for  XRead- 
BitmapFile. 

XmuReadBitmapData  is  equivalent  to  XReadBitmapFile,  except  that  this  routine 
processes  any  type  of  stream  input,  and  it  does  not  create  a  pixmap  containing  the  resulting 
data.  This  is  useful  when  you  want  to  create  a  multi-plane  pixmap  from  the  data,  and  don't 
want  to  create  an  intermediate  one-plane  pixmap. 

Related  Commands 

XmuCreatePixmapFromBitmap,  XmuCreateStippledPixmap,  XmuDrawLogo, 
XmuDrawRoundedRectangle,  XmuFillRoundedRectangle,  XmuLocateBitmap- 
File, XmuReadBitmapDataFromFile,  XmuReleaseStippledPixmap. 
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XmuReadBitmapDataFromFile      \ Xmu- Graphics  Functions- 
Name 

XmuReadBitmapDataFromFile  —  read  and  check  bitmap  data  from  a  file. 
Synopsis 

#include  <Xll/Xmu/Drawing.h> 

int  XmuReadBitmapDataFromFile  ( filename,  width,  height,  datap, 
x_hot ,  y_hot) 

char  * filename; 

unsigned  int  * width,  *height; 

unsigned  char  **datap; 

int   *x_hot,    *y_hot; 

Arguments 

fi  1  ename         Specifies  the  file  to  read  from. 

wi  dth  Returns  the  width  of  the  bitmap. 

height  Returns  the  height  of  the  bitmap. 

da  t  ap  Returns  the  parsed  bitmap  data. 

x_hot  Returns  the  x  coordinate  of  the  hotspot. 

y_h  o  t  Returns  the  y  coordinate  of  the  hotspot. 

Description 

XmuReadBitmapDataFromFile  reads  a  standard  bitmap  file  description  from  the  specified 
file,  and  returns  the  parsed  data  in  a  format  suitable  for  passing  to  XCreatePixmapFrom- 
BitmapData.  The  return  value  of  the  function  has  the  same  meaning  as  the  return  value  for 

XReadBitmapFile. 

Unlike  XReadBitmapFile,  this  function  does  not  create  a  pixmap.  This  function  is  useful 
when  you  want  to  create  a  multi-plane  pixmap  without  creating  an  intermediate  one-plane  pix 
map. 

Related  Commands 

XmuCreatePixmapFromBitmap,  XmuCreateStippledPixmap,  XmuDrawLogo, 
XmuDrawRoundedRect angle,  XmuFillRoundedRectangle,  XmuLocateBitmap- 
File,  XmuReadBitmapData,  XmuReleaseStippledPixmap. 
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x  XmuReleaseStippledPixmap 

— Xmu  -  Graphics  Functions ' 

Name 

XmuReleaseStippledPixmap  — release  pixmap  created  with  XmuCreateStippled- 
Pixmap. 

Synopsis 

#include  <Xll/Xmu/Drawing.h> 

void  XmuReleaseStippledPixmap  (screen,  pixmap) 

Screen  *  scree/2; 

Pixmap  pixmap; 

Arguments 

screen  Specifies  the  screen  the  pixmap  was  created  on. 

pixmap  Specifies  the  pixmap  to  free. 

Description 

XmuReleaseStippledPixmap  frees  a  pixmap  created  with  XmuCreateStippled- 
Pixmap,  to  maintain  correct  cache  reference  counts. 

Related  Commands 

XmuCreatePixmapFromBitmap,  XmuCreateStippledPixmap,  XmuDrawLogo, 
XmuDrawRoundedRectangle,  XmuFillRoundedRectangle,  XmuLocateBitmap- 
File, XmuReadBitmapData, XmuReadBitmapDataFromFile. 
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XmuRemoveCloseDisplayHook 


•Xmu  -  CloseDisplay  Hook- 


Name 

XmuRemoveCloseDisplayHook  —  remove  registered  close  display  callback  function. 

Synopsis 

^include  <Xll/Xmu/CloseHook.h> 

Bool  XmuRemoveCloseDisplayHook  ( display,  handle,  func,  arg) 

Display  ^display; 

CloseHook  handle; 

int  (*func)  ()  ; 

caddr_t    arg; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

handl  e  Specifies  the  callback  by  ID,  or  NULL. 

func  Specifies  the  callback  by  function. 

arg  Specifies  the  function  data  to  match. 

Description 

XmuRemoveCloseDisplayHook  unregisters  a  callback  that  has  been  registered  with  Xmu- 
AddCloseDisplayHook.  If  handle  is  not  NULL,  it  specifies  the  ID  of  the  callback  to 
remove,  and  the  func  and  arg  parameters  are  ignored.  If  handle  is  NULL,  the  first  callback 
found  to  match  the  specified  func  and  arg  will  be  removed.  Returns  True  if  a  callback  was 
removed,  else  returns  False. 

Related  Commands 

XmuAddCloseDisplayHook,  XmuLookupCloseDisplayHook. 
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/  XmuScreenOfWindow 

—Xmu  -Window  Utility  Functions ' 

Name 

XmuScreenOfWindow  —  returns  a  pointer  to  the  Screen  structure  for  the  specified  window. 

Synopsis 

#include  <Xll/Xmu/WinUtil .h> 

Screen  *XmuScreenOfWindow ( display,  w) 

Display  *display; 

Window  w; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpe nD  i  s p  1  a y . 

w  Specifies  the  window. 

Description 

XmuScreenOfWindow  returns  a  pointer  to  the  Screen  structure  that  describes  the  screen  on 
which  the  specified  window  was  created. 

Related  Commands 

XmuClientWindow, XmuUpdateMapHints. 
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XmuSimpleErrorHandler 


•Xmu  -  Error  Handler  Functions — 


Name 

XmuSimpleErrorHandler  —  an  error  handler  that  ignores  certain  errors. 

Synopsis 

tinclude  <Xll/Xmu/Error .h> 

int  XmuSimpleErrorHandler  (  display,  error) 

Display  *display; 

XErrorEvent  *error; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

error  Specifies  the  error  event 

Description 

XmuSimpleErrorHandler  ignores  BadWindow  errors  for  XQueryTree  and  XGet- 
WindowAttributes,  and  ignores  BadDrawable  errors  for  XGetGeometry;  it  returns 
zero  in  those  cases.  Otherwise,  it  prints  the  default  error  message,  and  returns  a  non-zero  value 
if  the  caller  should  consider  exiting,  and  zero  if  the  caller  should  not  exit. 

Related  Commands 

XmuPrintDefaultErrorMessage. 


758  Xlib  Reference  Manual 


— Xmu  -  Standard  Co  lor  maps- 


Name 


XmuStandardColormap 


XmuStandardColormap  —  create  one  standard  colormap. 
Synopsis 

#include  <Xll/Xmu/StdCmap.h> 

XmuStandardColormap  (display,  screen,  visualid,  depth,  property, 
cmapf  red_maxr  green_max,  blue_max) 

Display  display; 

int  screen ; 

VisuallD  visualid; 

unsigned  int  depth; 

Atom  property; 

Colormap  cmap; 

unsigned  long  red_max,  green_max,  blue_max; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  XOpenDisplay. 

screen  Specifies  the  screen  of  the  display, 

visualid  Specifies  the  visual  type, 

depth  Specifies  the  visual  depth, 

property  Specifies  the  standard  colormap  property. 

cmap  Specifies  the  colormap  ID,  or  None. 

red_max  Specifies  the  red  allocation. 

green_max  Specifies  the  green  allocation. 

bl  ue_max  Specifies  the  blue  allocation. 

Description 

XmuStandardColormap  creates  one  standard  colormap  for  the  given  screen,  visualid,  and 
visual  depth,  with  the  given  red,  green,  and  blue  maximum  values,  with  the  given  standard 
property  name.  Upon  success,  it  returns  a  pointer  to  an  XStandardColormap  structure 
which  describes  the  newly  created  colormap.  Upon  failure,  it  returns  NULL.  If  cmap  is  the 
default  colormap  of  the  screen,  the  standard  colormap  will  be  defined  on  the  default  colormap; 
otherwise  a  new  colormap  is  created. 

Resources  created  by  this  function  are  not  made  permanent;  that  is  the  caller's  responsibility. 
Related  Commands 

XmuAllStandardColormaps,  XmuCreateColormap,  XmuDeleteStandard- 
Colormap,  XmuGetColormapAllocation,  XmuLookupStdCmp,  XmuVisual- 
StandardColormaps. 
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XmuUpdateMapHints  V_Xmu  _  Wlndo«  utuity  Functions- 

Name 

XmuUpdateMapHints  —  set  WM_HINTS  flags  to  US  Size  and  usPosition. 

Synopsis 

#include  <Xll/Xmu/WinUtil .h> 

Bool  XmuUpdateMapHints (display,  w,  hints) 

Display  * display; 

Window  w; 

XSizeHints  *hints; 

Arguments 

di  spl  ay  Specifies  a  connection  to  an  X  server;  returned  from  XOpenD  i  s p  1  a y . 

win  Specifies  the  window. 

hints  Specifies  the  new  hints,  or  NULL. 

Description 

XmuUpdateMapHints  clears  the  PPosition  and  PSize  flags  and  sets  the  USPosition 
and  USSize  flags  in  the  hints  structure,  and  then  stores  the  hints  for  the  window  using  XSet- 
WMNormalHints  and  returns  True.  If  NULL  is  passed  for  the  hints  structure,  then  the  current 
hints  are  read  back  from  the  window  using  XGetWMNormalHints  the  flags  are  set  as 
described  above,  the  property  is  reset,  and  True  is  returned.  XmuUpdateMapHints  returns 
False  if  it  was  unable  to  allocate  memory  or,  when  NULL  is  passed,  if  the  existing  hints  could 
not  be  read. 

Related  Commands 

XmuClientWindow,  XmuScreenOf Window. 
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— Xmu  -  Standard  Co  lor  maps - 


XmuVisualStandardColormaps 


Name 

XmuVisualStandardColormaps  —  create  all  standard  colormaps  for  given  visual  and  screen. 

Synopsis 

#include   <Xll/Xmu/StdCmap.h> 

XmuVisualStandardColormaps ( display,    screen,    visualid,    depth, 
replace,    retain) 

Display   *display; 

int    screen; 

VisuallD   visualid; 

unsigned   int    depth; 

Bool   replace; 

Bool    retain; 

Arguments 

display  Specifies  a  connection  to  an  X  server;  returned  from  xopenDisplay. 

screen  Specifies  the  screen  of  the  display. 

visualid  Specifies  the  visual  type. 

depth  Specifies  the  visual  depth. 

replace  Specifies  whether  or  not  to  replace  the  standard  colormap  property. 

retain  Specifies  whether  or  not  to  retain  the  colormap  resource  permanently. 

Description 

XmuVisualStandardColormaps  creates  all  of  the  appropriate  standard  colormaps  for  a 
given  visual  on  a  given  screen,  and  optionally  redefines  the  corresponding  standard  colormap 
properties. 

If  replace  is  True,  any  previous  definition  will  be  removed.  If  retain  is  True,  new  pro 
perties  will  be  retained  for  the  duration  of  the  server  session.  This  function  returns  zero  on  fail 
ure,  non-zero  on  success.  On  failure,  no  new  properties  will  be  defined,  but  old  ones  may  have 
been  removed  if  replace  was  True. 

Not  all  standard  colormaps  are  meaningful  to  all  visual  classes.  This  routine  will  check  and 
define  the  following  properties  for  the  following  classes,  provided  that  the  size  of  the  colormap 
is  not  too  small.  For  DirectColor  and  Pseudocolor:  RGB_DEFAULT_MAP, 

RGB_BEST_MAP,  RGB_RED_MAP,  RGB_GREEN_MAP,  RGB_BLUE_MAP,  and  RGB_GRAY_MAP.  For 
TrueColor  and  StaticColor:  RGB_BEST_MAP  .  For  Grayscale  and  StaticGray: 
RGB_GRAY_MAP . 

Related  Commands 

XmuAllStandardColormaps,  XmuCreateColormap,  XmuDeleteStandard- 
Colormap,  XmuGetColormapAllocation,  XmuLookupStdCmp,  XmuStandard- 
Colormap. 
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:apPro jecting 


join_style 


: 


JoinMiter 


JoinBevel 


fill_style 

Tile  GC  foreground 


illSolid 

Stipple 


GC  background  Q  Undrawn  Pixels  [~~| 

iled      FillStippled  FillOpaqueStippled 


I 


' I  .  „.. 


fill    rule 


Outline  of  polygon  to  fill 


EvenOddRule 


ArcPieSlice 


WindingRule 


subwindow  mode 


inciudeinf  eriors     Graphics  drawn  with  this  setting  will  appear  through  all  mapped 

subwindows,  but  not  through  siblings. 
:iipByChiidren         Graphics  drawn  will  not  draw  through  any  other  window  that  has 

a  background. 


graphics_exposures 


True       Generate  GraphicsExpose  Or  NoExpose  events  when  XCopyArea  Or 

:copyFiane  is  called  with  this  GC. 
False    Don't  generate  GraphicsExpose  or  NoExpose  events. 
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